agentleFS
KemetraKemetra/Seshat-BI/.claude/skills/approval-evidence-pack/SKILL.md

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.

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
  1. Distinctive:

    MUST NOT create truth: no defining/approving business meaning (metric, mapping, rollup, segment), no PII publish-safety ruling.

    line 117
  2. Very specific:

    MUST NOT grant approval, populate the approvals[] slot, or move a readiness stage to pass (named-human / Core Authority only).

    line 119
  3. Distinctive:

    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 …

    line 121
  4. Distinctive:

    MUST NOT emit a numeric / maturity / confidence score (hard rule #9), and MUST NOT emit a completeness / "N of M" count (Clarifications …

    line 123
  5. Distinctive:

    NOT emit a completeness / "N of M" count (Clarifications 2026-06-25).

    line 124
  6. Distinctive:

    When a required Core Authority input is absent, unfilled, a blank template, or unreadable, the module SURFACES it as a BLOCKER naming the …

    line 128
  7. Very specific:

    Read mappings/<table>/readiness-status.yaml.

    line 172
  8. Very specific:

    NOT re-run or re-implement the AL1 rule (src/seshat/rules/assumptions.py).

    line 198
  9. Very specific:

    Read docs/quality/parked-on.yaml.

    line 203
  10. Very specific:

    Write only mappings/<table>/approval-evidence-pack-<stage>.md.

    line 229
  11. Very specific:

    After a run, git status shows the only new/modified file is the one derived pack at mappings/<table>/approval-evidence-pack-<stage>.md.

    line 290
  12. Distinctive:

    Do NOT invent or fabricate any section's content when its source is missing -- record a blocker naming the path.

    line 298
  13. Very specific:

    Do NOT write, grant, or imply an approval.

    line 300
  14. Very specific:

    Do NOT edit, re-author, or redefine any source artifact (readiness-status.yaml, the readiness docs, the metric contracts, the parked-on …

    line 302
  15. Distinctive:

    Do NOT paraphrase a committed grain / rollup / segment / PII ruling into fresh wording (FR-013 -- link and cite only).

    line 304
  16. Distinctive:

    Do NOT emit a numeric confidence / health / maturity score or a completeness count.

    line 306
  17. Distinctive:

    Do NOT read a live database or PBIP model.

    line 308
  18. Very specific:

    Do NOT add a seshat check rule, define a new readiness stage, or alter a gate.

    line 310
  19. Distinctive:

    Do NOT surface a stage AFTER the selected one (FR-020).

    line 311
  20. Distinctive:

    Do NOT inline C086 / retail_store_sales specifics into the pack, the template, or this doc.

    line 312
  21. Distinctive:

    When a table is driven end-to-end, the conductor may invoke this skill BEFORE a named-human stage approval (Mapping / Semantic Model / …

    line 339

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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 -- see docs/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 to mappings/<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 to mappings/<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 to approvals[]. 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: F035 On-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-stage status, evidence[], blocking_reasons[], top-level blocking_reasons[], and approvals[] (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 whose readiness.status is not pass, 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 of templates/approval-evidence-pack.md for the selected (table, stage). This is the ONLY file the module writes.

Approved step it EXECUTES

  • none (capability is artifact-writing, not execution-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 to pass (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.

  1. docs/readiness/<stage>-ready.md -- gate requirements (section 1).
  2. mappings/<table>/readiness-status.yaml -- readiness state + blockers + approvals (sections 2, 3, 7).
  3. mappings/<table>/metrics/*.yaml -- AL1 assumption signal per contract (section 4) and the pending-contract set (section 6).
  4. docs/quality/parked-on.yaml -- blocking parked-on edges (section 5).

Stage-key -> readiness-doc map (1:1)

Stage keyApproval gate?Readiness doc
source_readydata-owner confirm (proposed semantics/PII)docs/readiness/source-ready.md
mapping_readyYES (analyst / governance)docs/readiness/mapping-ready.md
silver_readymechanical (no stage approval)docs/readiness/silver-ready.md
gold_readymechanical (no stage approval)docs/readiness/gold-ready.md
semantic_model_readyYES (metric owner)docs/readiness/semantic-model-ready.md
dashboard_readyYES (report owner)docs/readiness/dashboard-ready.md
publish_readyYES (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)

SituationWhat the composer does
readiness-status.yaml is missing / unreadabletop-level BLOCKER naming the path; assert no stage status as fact; slot stays empty (FR-011, US2.1)
The selected stage status is not_startedsurface 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 unreadablerecord that unreadable path as a BLOCKER rather than silently dropping it (FR-011, US2.3)
The prior stage is not yet passsurface "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 filledForm 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 rulingLINK-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 requestedrefuse; return the four statuses + evidence + blockers (hard rule #9; FR-012)
Live data or a PBIP model is requested as a sourceout 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 to pass.
  • 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 check rule, 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 at mappings/<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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.