approval-evidence-pack
Skill2 starsChanged 4 months agoApache-2.0View on GitHub
Assemble a reviewable evidence pack behind a readiness approval in the Seshat BI repo. Use when someone asks to package the evidence for a stage sign-off. Read-only: it collects committed evidence and never grants the approval.
In this repository60 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- approval-consoleSkill
- 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
- kpi-contract-builderSkill
- 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
Show its rules and text
We split this skill into the rules it gives an agent
21 rules. About 0 are common, 12 are distinctive, and 9 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈12
Distinctive · estimate
This author's own choices. Worth a look.
9
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 117
MUST NOT create truth: no defining/approving business meaning (metric, mapping, rollup, segment), no PII publish-safety ruling.
- Very specific: line 119
MUST NOT grant approval, populate the approvals[] slot, or move a readiness stage to pass (named-human / Core Authority only).
- Distinctive: line 121
MUST NOT connect to a DB or external service, read a live Power BI/PBIP surface, or invoke a deferred execution adapter (F016) or spec-only …
- Distinctive: line 123
MUST NOT emit a numeric / maturity / confidence score (hard rule #9), and MUST NOT emit a completeness / "N of M" count (Clarifications …
- Distinctive: line 124
NOT emit a completeness / "N of M" count (Clarifications 2026-06-25).
- Distinctive: line 128
When a required Core Authority input is absent, unfilled, a blank template, or unreadable, the module SURFACES it as a BLOCKER naming the …
- Very specific: line 172
Read mappings/<table>/readiness-status.yaml.
- Very specific: line 198
NOT re-run or re-implement the AL1 rule (src/seshat/rules/assumptions.py).
- Very specific: line 203
Read docs/quality/parked-on.yaml.
- Very specific: line 229
Write only mappings/<table>/approval-evidence-pack-<stage>.md.
- Very specific: line 290
After a run, git status shows the only new/modified file is the one derived pack at mappings/<table>/approval-evidence-pack-<stage>.md.
- Distinctive: line 298
Do NOT invent or fabricate any section's content when its source is missing -- record a blocker naming the path.
- Very specific: line 300
Do NOT write, grant, or imply an approval.
- Very specific: line 302
Do NOT edit, re-author, or redefine any source artifact (readiness-status.yaml, the readiness docs, the metric contracts, the parked-on …
- Distinctive: line 304
Do NOT paraphrase a committed grain / rollup / segment / PII ruling into fresh wording (FR-013 -- link and cite only).
- Distinctive: line 306
Do NOT emit a numeric confidence / health / maturity score or a completeness count.
- Distinctive: line 308
Do NOT read a live database or PBIP model.
- Very specific: line 310
Do NOT add a seshat check rule, define a new readiness stage, or alter a gate.
- Distinctive: line 311
Do NOT surface a stage AFTER the selected one (FR-020).
- Distinctive: line 312
Do NOT inline C086 / retail_store_sales specifics into the pack, the template, or this doc.
- Distinctive: line 339
When a table is driven end-to-end, the conductor may invoke this skill BEFORE a named-human stage approval (Mapping / Semantic Model / …
≈ “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
approval-evidence-pack
- Roadmap feature: F035 On-disk spec:
specs/063-approval-evidence-pack/(dir 063 == F035; when the dir number and the F-number disagree, the roadmap F-number wins). - Authority category: Product Module /
artifact-writing(the F024 enumerated declaration -- seedocs/architecture/product-modules.md).
Four of the seven readiness stages -- Mapping Ready, Semantic Model Ready,
Dashboard Ready, Publish Ready -- require a NAMED-HUMAN approval the agent is
constitutionally forbidden to grant for itself (Principle V; recorded in each
table's mappings/<table>/readiness-status.yaml approvals[]). When such a human
is asked to sign a stage gate, the evidence they need is real but SCATTERED: the
per-stage readiness doc says what the gate requires; readiness-status.yaml carries
the four-status state and the open blockers; the AL1 assumption ledger (surfaced
from the metric contracts) may flag an unresolved judgment call; the parked-on map
may show the work is blocked on a shared bottleneck. This skill is the COMPOSER
that assembles those scattered, already-committed artifacts into ONE ordered
PRE-approval pack for one (table, stage). It FILLS the pack; it originates no
evidence and owns no truth. Every line points back at the artifact it came from;
any source that is missing or unfilled is a BLOCKER, never papered over with
invented content. The pack surfaces the gate's readiness picture; it never signs it.
Boundary against neighbouring shipped work (read first)
- F028 evidence-pack-generator (
.claude/skills/evidence-pack-generator/, spec 022) composes a LATE-STAGE, per-table 10-section pack for the Semantic Model -> Dashboard -> Publish window only, written tomappings/<table>/evidence-pack-index.md/evidence-pack-summary.md. This module is a PRE-approval packet GENERIC across ALL seven stage gates (stage parameter), scoped to what ONE gate needs, written tomappings/<table>/approval-evidence-pack-<stage>.md. It REUSES F028's surface-never-assert discipline and empty-approvals rule verbatim in spirit; it does NOT edit F028 and does NOT re-render F028's 10 sections. - F027 Approval Console (
.claude/skills/approval-console/,templates/approval-request.md/approval-decision.md, spec 021) packages ONE raised judgment call into a decidable request and TRANSCRIBES a human's answer back into the committed artifacts. This module packages a WHOLE-GATE readiness picture (many pieces of evidence, not one question) and WRITES NOTHING BACK -- it never transcribes an answer, never appends toapprovals[]. The two compose: this pack is the evidence a human reads BEFORE the Approval Console records their signature.
This module adds NO new readiness stage and NO new seshat check rule -- it
composes results other tools recorded (the F024 Product Module boundary).
Authority declaration (F024) -- the filled module contract
This module declares EXACTLY ONE of the five F024 authority categories. Quoted
verbatim from docs/architecture/product-modules.md: a Product Module is "a
focused tool that consumes Core Authority and presents, summarizes, or derives from
it. A module MUST declare exactly one capability level: read-only |
artifact-writing | execution-capable. It never creates truth." This module's
capability level is artifact-writing: it derives one committed artifact (the
pack) from committed evidence, and -- per the matrix -- MAY write derived evidence
but MUST NOT execute.
The filled templates/module-contract.md declaration follows.
Module Contract -- Approval Evidence Pack
- Authority category: Product Module
- Capability level:
artifact-writing(exactly one) - Product layer:
6(the functional axis -- see docs/roadmap/roadmap.md; orthogonal to category; sibling of the F028 evidence pack) - Roadmap feature:
F035On-disk spec:specs/063-approval-evidence-pack/ - Owner: the named human who signs the selected stage gate (analyst / metric owner / report owner / data-owner / governance, per the stage)
- Status: Authored (docs/templates; no runtime code -- the agent is the runtime)
What it does (one line)
Composes the committed pre-approval evidence for ONE (table, stage) -- gate requirements, four-status state for the selected + prior stages, open blockers, per-contract unresolved assumptions, blocking parked-on edges, pending contracts -- into one ordered pack ending with an EMPTY approval slot, inventing nothing.
Core Authority it READS
It reads; it never writes these.
docs/readiness/<stage>-ready.md-- what the selected gate requires and which named human (if any) must sign.mappings/<table>/readiness-status.yaml-- per-stagestatus,evidence[],blocking_reasons[], top-levelblocking_reasons[], andapprovals[](the recorded state, blockers, and any already-recorded approval the pack surfaces).mappings/<table>/metrics/*.yaml-- the metric contracts: the AL1 assumption signal surfaced per offending contract (FR-021), and the pending-contract set (those whosereadiness.statusis notpass, FR-008).docs/quality/parked-on.yaml-- the parked-on dependency edges; surface any that block this table's stage.
Derived evidence it WRITES
Composed FROM committed evidence; never a new approval, metric definition, or stage change.
mappings/<table>/approval-evidence-pack-<stage>.md-- one filled copy oftemplates/approval-evidence-pack.mdfor the selected (table, stage). This is the ONLY file the module writes.
Approved step it EXECUTES
- none (capability is
artifact-writing, notexecution-capable; it composes and STOPS, touching no DB and publishing nothing).
Forbidden operations (the matrix says NO)
These hold for EVERY Product Module regardless of capability level:
- MUST NOT create truth: no defining/approving business meaning (metric, mapping, rollup, segment), no PII publish-safety ruling.
- MUST NOT grant approval, populate the
approvals[]slot, or move a readiness stage topass(named-human / Core Authority only). - MUST NOT connect to a DB or external service, read a live Power BI/PBIP surface, or invoke a deferred execution adapter (F016) or spec-only runtime (F031-F033).
- MUST NOT emit a numeric / maturity / confidence score (hard rule #9), and MUST NOT emit a completeness / "N of M" count (Clarifications 2026-06-25).
How it handles a missing input
When a required Core Authority input is absent, unfilled, a blank template, or unreadable, the module SURFACES it as a BLOCKER naming the missing/unreadable path and stops treating that source as content -- it never fabricates the input, self-approves, or proceeds past the missing gate (Principle V; stop-and-ask).
The input contract (committed-only)
The pack composes EXACTLY these committed sources -- no live DB, no PBIP model, no Power BI execution adapter (F016), no spec-only runtime (F031-F033), no network. Any live signal must already be recorded as committed evidence before the pack can cite it.
docs/readiness/<stage>-ready.md-- gate requirements (section 1).mappings/<table>/readiness-status.yaml-- readiness state + blockers + approvals (sections 2, 3, 7).mappings/<table>/metrics/*.yaml-- AL1 assumption signal per contract (section 4) and the pending-contract set (section 6).docs/quality/parked-on.yaml-- blocking parked-on edges (section 5).
Stage-key -> readiness-doc map (1:1)
| Stage key | Approval gate? | Readiness doc |
source_ready | data-owner confirm (proposed semantics/PII) | docs/readiness/source-ready.md |
mapping_ready | YES (analyst / governance) | docs/readiness/mapping-ready.md |
silver_ready | mechanical (no stage approval) | docs/readiness/silver-ready.md |
gold_ready | mechanical (no stage approval) | docs/readiness/gold-ready.md |
semantic_model_ready | YES (metric owner) | docs/readiness/semantic-model-ready.md |
dashboard_ready | YES (report owner) | docs/readiness/dashboard-ready.md |
publish_ready | YES (data-owner / governance) | docs/readiness/publish-ready.md |
The four highlighted approvals[] gates are mapping_ready,
semantic_model_ready, dashboard_ready, publish_ready (readiness-model.md).
silver_ready and gold_ready are MECHANICAL gates with no stage approval ->
Form C. source_ready needs a data-owner confirm of proposed semantics/PII but is
not one of the four highlighted approvals[] stages -- surface its recorded state
and any confirm the source records; do not manufacture a fresh approvals[] slot
the spine does not define for it.
Compose steps (numbered; do not reorder)
1. Resolve the (table, stage) and read the state
Read mappings/<table>/readiness-status.yaml. This is read-only; it fixes the
recorded status of the selected stage and every prior stage, the blockers, and any
recorded approvals[]. If the file is MISSING or unreadable, do not fabricate any
status: record a top-level BLOCKER naming the missing path (FR-011) and still
render the pack shell with the approval slot empty.
2. Section 1 -- what this gate requires
Open docs/readiness/<stage>-ready.md via the map above. Summarise/link its gate
requirements and the required owner/approval. Do NOT re-author the readiness doc;
link and point to it. If it is missing/unreadable -> a BLOCKER naming the path.
3. Section 2 -- readiness state (selected + prior only)
List the selected stage and every stage BEFORE it in the seven-stage order, with
each status VERBATIM (not_started | blocked | warning | pass) and its
evidence[] paths. NEVER surface a stage AFTER the selected one (FR-020). Never
assert a status the source does not record (FR-004).
4. Section 3 -- open blockers
List every blocking_reasons[] entry for the selected stage plus the cross-cutting
top-level blocking_reasons[], each traceable to its source (FR-005). If none are
recorded, say so -- do not read absence-of-a-block as readiness.
5. Section 4 -- unresolved assumptions (per contract)
Surface the AL1 assumption-ledger signal from mappings/<table>/metrics/*.yaml,
PER offending contract (FR-021): each item names the specific
mappings/<table>/metrics/<Metric>.yaml file and the recorded contradiction. Do
NOT re-run or re-implement the AL1 rule (src/seshat/rules/assumptions.py); surface
its recorded result only. Do NOT resolve the assumption (Principle V). An
unreadable contract -> a BLOCKER naming the path (FR-011).
6. Section 5 -- blocking parked-on edges
Read docs/quality/parked-on.yaml; surface any edge that blocks this table's stage,
citing its recorded blocked, parked_on, doc, and evidence (FR-007). If none
apply, say so.
7. Section 6 -- pending contracts (FR-008, RESOLVED)
List mappings/<table>/metrics/*.yaml contracts whose readiness.status is not
pass (the existing on-disk set, read-only). Do NOT introduce a new per-stage
pending list and do NOT reinterpret the KPI-layer Seeded/Planned markers. For any
business-rule content, LINK-AND-CITE ONLY (see the FR-013 boundary below): cite the
contract path, never paraphrase its grain/rollup/segment/PII ruling. A
missing/unreadable contract -> a BLOCKER (FR-011).
8. Section 7 -- the terminal approval slot (exactly one form)
Pick the ONE form that matches the source and delete the other two:
- Form A (EMPTY slot) -- the selected stage is an approval gate and
approvals[]has no entry for it: render an empty slot (owner: "",at: "") for the named human. The module CANNOT fill it. - Form B (RECORDED, read-only) --
approvals[]already records an entry for this stage: surface{ stage, owner, at }from source; offer NO fresh slot and overwrite nothing (FR-016). - Form C (NOT APPLICABLE) -- the stage is a mechanical gate
(
silver_ready/gold_ready): state "no stage-approval slot applies" and surface the mechanical gate result (FR-015) -- do NOT manufacture a human-approval seam the spine does not define.
9. STOP
Write only mappings/<table>/approval-evidence-pack-<stage>.md. Edit no source
artifact. Write no approval, move no stage to pass. Any judgment call surfaced in
the pack -- a grain/rollup/segment/PII ambiguity, a source disagreement, the stage
approval itself -- is a stop-and-ask for the named human (Principle V).
Surface, never assert -- the empty-approvals discipline (reused from F028)
The module is structurally INCAPABLE of writing approvals[], moving a stage to
pass, granting an approval, or defining business meaning (FR-009, FR-010). It
DISPLAYS values it read from Core Authority and records nothing back. The terminal
section is one of: an EMPTY slot only the named human fills; a read-only surfacing
of an already-recorded approval; or, for a mechanical gate, a "no stage-approval
applies" statement with the mechanical result. The decision belongs to the named
human via Core Authority; the pack reads-and-displays it.
No score, no count (hard rule #9)
The pack emits NO numeric confidence / health / maturity value and NO completeness
or "N of M" count. Readiness is expressed ONLY as the four explicit statuses
(not_started | blocked | warning | pass) + evidence[] + blocking_reasons[]
(FR-012). If a score or count is requested, refuse and return the four-status
picture with evidence and blockers.
Honest-state rules (never invent, never silently reconcile)
| Situation | What the composer does |
readiness-status.yaml is missing / unreadable | top-level BLOCKER naming the path; assert no stage status as fact; slot stays empty (FR-011, US2.1) |
The selected stage status is not_started | surface not_started as recorded; do NOT treat absence of a block as readiness; slot stays empty (US2.2) |
| A metric contract the ledger references is unreadable | record that unreadable path as a BLOCKER rather than silently dropping it (FR-011, US2.3) |
The prior stage is not yet pass | surface "gate not yet reachable -- prior stage not pass" as a blocker; never imply the current gate is signable while an earlier stage is open (edge case) |
approvals[] for the selected stage is ALREADY filled | Form B: surface the recorded approval read-only (owner + date from source); offer NO fresh slot; overwrite nothing (FR-016) |
The stage is a mechanical gate (silver_ready / gold_ready) | Form C: "no stage-approval slot applies"; surface the mechanical result (FR-015) |
| A source records a grain / rollup / segment / PII ruling | LINK-AND-CITE ONLY (FR-013): cite the ruling's own recorded text + source path; NEVER paraphrase it into fresh wording; when in doubt, link rather than summarise |
| A numeric confidence/health score or an "N of M" count is requested | refuse; return the four statuses + evidence + blockers (hard rule #9; FR-012) |
| Live data or a PBIP model is requested as a source | out of scope; the composer reads only committed artifacts (FR-002) |
The FR-013 business-rule / PII boundary -- LINK-AND-CITE ONLY
For any evidence whose underlying artifact records a business-rule ruling (a metric
contract's grain / rollup / segment) or a PII publish-safety ruling, the pack MUST
only LINK and CITE the committed ruling -- it quotes/points at the committed
ruling's own recorded text and its source path and NEVER paraphrases the decision
into new wording that could read as a fresh judgment. The pack emits the citation +
a neutral pointer ("see <path>"), not a restatement; when in doubt it links rather
than summarises. This keeps the named human's business-rule/PII judgment the single
source of truth (Principle V/VII). These rulings do NOT widen the module's write
surface -- it remains structurally incapable of writing approvals[] or moving any
stage (FR-009/FR-010).
Generic only (Principle VII)
The template (templates/approval-evidence-pack.md) and any fixed section label
carry NO worked-example (C086 / retail_store_sales) label, grain key, or column
name. C086 appears only as a cited filled instance (see docs/worked-examples/).
The module resolves a generic mappings/<table>/ path from the table parameter
(FR-014, SC-006). ASCII only, UTF-8 no BOM (use -- and ->, no glyphs); short
repo-relative paths (Windows 260-char budget).
Composes-only proof
After a run, git status shows the only new/modified file is the one derived pack
at mappings/<table>/approval-evidence-pack-<stage>.md. No source artifact is
modified, readiness-status.yaml / approvals[] is unchanged, and no stage moved
to pass. The skill triggered no seshat check / retail validate run of its own
and opened no DB connection.
What the agent must NOT do
- Do NOT invent or fabricate any section's content when its source is missing -- record a blocker naming the path.
- Do NOT write, grant, or imply an approval; do NOT populate the
approvals[]slot; do NOT move any readiness stage topass. - Do NOT edit, re-author, or redefine any source artifact (readiness-status.yaml, the readiness docs, the metric contracts, the parked-on map).
- Do NOT paraphrase a committed grain / rollup / segment / PII ruling into fresh wording (FR-013 -- link and cite only).
- Do NOT emit a numeric confidence / health / maturity score or a completeness count.
- Do NOT read a live database or PBIP model; do NOT call the Power BI execution adapter (F016) or any spec-only runtime (F031-F033); do NOT publish / deploy.
- Do NOT add a
seshat checkrule, define a new readiness stage, or alter a gate. - Do NOT surface a stage AFTER the selected one (FR-020).
- Do NOT inline C086 / retail_store_sales specifics into the pack, the template, or this doc.
See also
- The output shape:
../../../templates/approval-evidence-pack.md(the generic copy-me pack). - The neighbour it composes AFTER, never edits: F028
../../../.claude/skills/evidence-pack-generator/SKILL.md(late-stage 10-section pack); the neighbour that records the signature it precedes: F027../../../.claude/skills/approval-console/SKILL.md. - The four-status / no-fake-confidence model:
../../../docs/readiness/readiness-model.md; the per-stage gate docs under../../../docs/readiness/. - The state artifact it reads:
../../../templates/readiness-status.yaml(schema); the filled copy lives atmappings/<table>/readiness-status.yaml(ADR 0004). - The AL1 assumption signal source:
../../../src/seshat/rules/assumptions.py(surfaced, never re-run). The parked-on map:../../../docs/quality/parked-on.yaml(DF1). - The authority contract:
../../../docs/architecture/product-modules.md(the five categories + the matrix),../../../templates/module-contract.md(the copy-me declaration filled above). - The spec:
../../../specs/063-approval-evidence-pack/spec.md. A filled worked example lives under../../../docs/worked-examples/.
Orchestration
When a table is driven end-to-end, the conductor may invoke this skill BEFORE a named-human stage approval (Mapping / Semantic Model / Dashboard / Publish Ready) to compose the pre-approval pack the human reads. This skill stays single-purpose: it composes the pack for one (table, stage), surfaces (never asserts) the state, ends with an empty approval slot, and STOPS at the human approval boundary. Recording the approval is the Approval Console (F027) / Core Authority, never here.
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.

