kpi-contract-builder
Skill2 starsChanged 4 months agoApache-2.0View on GitHub
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.
In this repository60 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- approval-consoleSkill
- approval-evidence-packSkill
- business-knowledge-interviewSkill
- capabilitiesSkill
- consumer-data-dictionarySkill
- cross-table-lineageSkill
- dagster-orchestration-adapterSkill
- dashboard-designSkill
- dashboard-intelligenceSkill
- dbt-transformation-adapterSkill
- evidence-pack-generatorSkill
- first-hour-compassSkill
- friendly-pr-reviewerSkill
- grain-confidence-reviewerSkill
- pbi-mcp-write-adapterSkill
- pbip-workflowSkill
- pbip-xraySkill
- pbir-authoring-adapterSkill
- portfolio-watchSkill
- powerbi-dashboard-designSkill
- pr-readiness-reviewerSkill
- readiness-viewerSkill
- release-notes-generatorSkill
- report-intent-interviewSkill
- retail-build-warehouseSkill
- retail-control-roomSkill
- retail-discover-portfolioSkill
- retail-governSkill
- retail-initSkill
- retail-onboard-tableSkill
- retail-orchestrateSkill
- retail-scaffoldSkill
- retail-semantic-checkSkill
- retail-validateSkill
- run-next-readinessSkill
- seshat-studioSkill
- showcase-buildSkill
- source-mappingSkill
- speckit-analyzeSkill
- speckit-checklistSkill
- speckit-clarifySkill
- speckit-constitutionSkill
- speckit-git-commitSkill
- speckit-git-featureSkill
- speckit-git-initializeSkill
- speckit-git-remoteSkill
- speckit-git-validateSkill
- speckit-implementSkill
- speckit-planSkill
- speckit-specifySkill
- speckit-tasksSkill
- speckit-taskstoissuesSkill
- bi-analyst-knowledgeSkill
- bi-bigdata-knowledgeSkill
- bi-dax-knowledgeSkill
- bi-python-knowledgeSkill
- bi-sql-knowledgeSkill
- retail-kpi-knowledgeSkill
The file
We split this skill into the rules it gives an agent
10 rules. About 0 are common, 2 are distinctive, and 8 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
8
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 34
Do NOT use it to define DAX (retail generate), to check a PBIP model (retail semantic-check), or to run the interview itself …
- Very specific: line 49
Read the source-coverage signal (read-only).
- Very specific: line 60
Check the Decision Store for the required kpi_definition + applicable policy_ruling decisions.
- Very specific: line 71
When an approved kpi_definition (+ every applicable approved policy_ruling) and a named eligible owner exist, build a ContractDraftRequest …
- Very specific: line 78
After the gold binding is materialized and validated, call finalize_project_metric_contract with a FinalizationContext (pass repo_root so …
- Very specific: line 89
NOT written into the persisted contract (which uses the engine's decision_refs / source_evidence).
- Very specific: line 108
Never self-grant an approval.
- Distinctive: line 114
Never fabricate a confidence score or percentage.
- Distinctive: line 115
Never write DAX / SQL / a silver or bronze binding into any field.
- Very specific: line 116
Never mutate registry.yaml.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
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.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

