kpi-contract-builder
Help a human turn a named-but-planned retail KPI into a governed, owner-ready project metric-contract by driving the shipped kpi_contracts engine (spec 124). On first contact, when no approved decisions exist yet, it assesses source answerability, lists the exact Decision Store decisions to get approved via business-knowledge-interview, and renders a preview with per-field provenance -- writing no YAML. Once the approved kpi_definition / policy_ruling decisions, a named eligible owner, and committed source evidence exist, it drives draft_project_metric_contract (a gold-blocked contract) and, after the gold binding is materialized, finalize_project_metric_contract. Use when someone asks to draft, author, or start a metric contract for a planned KPI in the Seshat BI repo. It never invents business meaning, DAX, SQL, gold columns, approvals, owners, a confidence score, or a registry entry; it never promotes a KPI to Seeded and never self-grants an approval.
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-11
- Stars
- ★ 2
- Forks
- 0
01 前言 Front Matter
- name
- kpi-contract-builder
- description
- Help a human turn a named-but-planned retail KPI into a governed, owner-ready project metric-contract by driving the shipped kpi_contracts engine (spec 124). On first contact, when no approved decisions exist yet, it assesses source answerability, lists the exact Decision Store decisions to get approved via business-knowledge-interview, and renders a preview with per-field provenance -- writing no YAML. Once the approved kpi_definition / policy_ruling decisions, a named eligible owner, and committed source evidence exist, it drives draft_project_metric_contract (a gold-blocked contract) and, after the gold binding is materialized, finalize_project_metric_contract. Use when someone asks to draft, author, or start a metric contract for a planned KPI in the Seshat BI repo. It never invents business meaning, DAX, SQL, gold columns, approvals, owners, a confidence score, or a registry entry; it never promotes a KPI to Seeded and never self-grants an approval.
02 资源文件 1
- 参考文档walkthrough.md3.0 KB
03 SKILL.md 正文
kpi-contract-builder
This skill is the agent-facing front door to the shipped kpi_contracts stage.
It does NOT reimplement contract authoring: the shipped kpi_contracts engine and
its kpi_answerability scorecard already exist (spec 124). This skill DRIVES
them and adds the first-contact assessment the engine deliberately refuses to do.
When to use
- Someone asks to draft / author / start a metric contract for a KPI that the
registry marks
planned(no seeded contract yet), or for a user-supplied custom KPI. - You are at the
kpi_contractsflow stage (downstream ofbusiness-knowledge-interview, upstream of silver/gold model planning).
Do NOT use it to define DAX (retail generate), to check a PBIP model
(retail semantic-check), or to run the interview itself
(business-knowledge-interview).
The two-trip flow
The shipped draft_project_metric_contract REQUIRES an approved decision, a named
owner, and committed source evidence; without them it raises
ContractDraftRefused. So the flow has two trips.
Trip 1 -- Assess & preview (the common first-contact case; writes nothing)
- Identify the KPI. Registry-known -> resolve its
generic_kpi_ref: KPI-MC-NNfrom theretail-kpi-knowledgeregistry (custom: false). User-supplied ->custom: true, no ref, no suggested id. - Read the source-coverage signal (read-only). NOTE: for a
lifecycle: plannedregistry entry -- the primary case for this skill --derive_answerabilityshort-circuits toPlannedbefore it inspects source roles, mapped concepts, domain, or evidence, so its status alone CANNOT tell you which fields are present. For a planned KPI, take the coverage signal from the registry entry's ownblockersandsource_roles/required_conceptsmetadata (and a committed source profile / source-map, if present) -- that is what surfaces abinds_togap. Usederive_answerability/render_answerability_artifactonly for its designed purpose (a coverage scorecard for SEEDED KPIs); consume it read-only, never persist or re-decide it -- contract authoring is a separate concern. - Check the Decision Store for the required
kpi_definition+ applicablepolicy_rulingdecisions. If any is missing/unapproved, do NOT call the engine (it will raise). - Render a PREVIEW: the contract's business body (clean; no provenance inside
values) + a
field_provenanceblock + the gap list. - Emit the decision-gap list: the exact
kpi_definition/policy_rulingdecisions to get approved (route tobusiness-knowledge-interview) and the owner to name. STOP. Write no YAML.
Trip 2 -- Draft & finalize (only when preconditions hold)
- When an approved
kpi_definition(+ every applicable approvedpolicy_ruling) and a named eligible owner exist, build aContractDraftRequestand calldraft_project_metric_contract. The result is a contract withreadiness.status: blockedand the reasonphysical gold binding is not materialized-- this is correct and expected until gold exists. - On explicit human confirmation, write the returned contract to
mappings/<table>/metrics/<Name>.yaml. - After the gold binding is materialized and validated, call
finalize_project_metric_contractwith aFinalizationContext(passrepo_rootso each referenced decision's approval evidence is re-verified); it promotes toreadiness.status: passONLY when every precondition (binding, decisions scoped to this KPI viascope.kpis, fresh evidence, and anamed_human_approvalequal to the eligible approver of a referencedkpi_definition) holds. The skill never setspassitself.
field_provenance (preview only; five-value origin vocabulary)
Rendered by this skill in the PREVIEW to show where each field came from. It is
NOT written into the persisted contract (which uses the engine's decision_refs
/ source_evidence). It is NEVER inserted inside a business value.
field_provenance:
formula_intent: { origin: knowledge, ref: "KPI-MC-02/net-sales.md", resolved: true }
binds_to: { origin: profile, ref: "source-profile.md#net_amount", resolved: false }
grain: { origin: human, ref: "interview 2026-07-13", resolved: true }
cost_method: { origin: gap, ref: "", resolved: false }
Origin is exactly one of: knowledge (transcribed from a generic
retail-kpi-knowledge contract), profile (proposed from the read-only source
profile -- never self-justifying), human (a recorded answer / approved
decision reference), provisional (a live unapproved answer shown in preview
only), gap (un-inferable). provisional and gap are never resolved: true;
either on a required field means the drafted contract stays readiness.status: blocked.
Hard stops
- Never self-grant an approval. The
owneris REQUIRED at draft time (draft_project_metric_contractrefuses an empty owner and persists the one you supply) -- so a named eligible owner must be identified before Trip 2; that is a human answer, not an agent invention. What the skill never fills isapprovalsand never setsreadiness.status: pass-- promotion topassis the named-human step performed byfinalize_project_metric_contract. - Never fabricate a confidence score or percentage.
- Never write DAX / SQL / a silver or bronze binding into any field.
- Never mutate
registry.yaml; never suggest aKPI-MCid for a custom KPI; never promote a KPI from Planned to Seeded. - For a
plannedKPI, contribute identity / concepts / roles / blockers only -- never an inventedformula_intent.
04 同仓库更多 Skills
fake-skill
A fixture skill with declaring frontmatter, used as positive shipped evidence.
fake-skill
A fixture skill with declaring frontmatter, used as positive shipped evidence.
bare-skill-no-frontmatter
暂无简介
fake-skill
A fixture skill with declaring frontmatter, used as positive shipped evidence.
retail-kpi-knowledge
Retail KPI / metric-contract reasoning layer for BI agents in the Seshat BI project. Use when an agent must reason about the BUSINESS MEANING of a retail KPI before any implementation — defining a KPI in business terms, classifying additivity (fully/semi/non-additive), identifying grain, listing required source fields, resolving ambiguity (gross vs net, VAT, returns, cost method, same-store), choosing an MVP KPI pack, reviewing a metric contract for completeness, or preparing a clean handoff to an implementation layer. Also use it to classify KPI sufficiency or prepare an owner policy decision packet. This is a meaning/definition + review layer, not an executor: it does not write DAX/SQL/Python, grant readiness, approve policy, or design dashboards. See INDEX.md for live/planned routes; registry.yaml is the authoritative machine-readable inventory.
bi-sql-knowledge
SQL reasoning, validation, reconciliation, transformation, diagnostics, and anti-pattern knowledge layer for Seshat BI agents. Use when a task involves reasoning about source SQL: source profiling, table grain, keys & uniqueness, joins & fan-out amplification, aggregation correctness, COUNT/NULL semantics, deduplication, validation queries, reconciliation queries, silver/gold transformation logic, window/date-time analytics, SQL anti-patterns, or basic SQL performance reasoning, or interpretation of a supplied sanitized PostgreSQL JSON execution plan. The SQL counterpart to bi-dax-knowledge. It is a thinking & validation layer, not a database executor, runtime validator, dbt/Dagster project, or automatic tuning service.