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

evidence-pack-generator

Skill2 starsChanged 4 months agoApache-2.0View on GitHub

Compose a single readable 10-section evidence pack for a table/report at the late readiness stages (Semantic Model Ready -> Dashboard Ready -> Publish Ready) in the Seshat BI repo. Use when someone asks to "assemble the evidence pack", "gather everything for the data-owner sign-off", or "show the full late-stage evidence for this table". This is a Product Module, artifact-writing: it READS the already-committed upstream artifacts, renders the ordered 10-section pack index + one-page summary, records each section's status (one of four) with evidence and blockers, and SURFACES the recorded publish_ready state read from readiness-status.yaml -- then STOPS. It invents NO section content (a missing or unfilled source is a blocker, never fabricated), embeds the shipped F013 handoff pack as section 08 without re-authoring it, writes NO approval, moves NO stage to pass, edits NO source artifact, runs NO live DB/PBIP read, and emits NO numeric confidence/health score.

The file

Show its rules and text

We split this skill into the rules it gives an agent

22 rules. About 0 are common, 11 are distinctive, and 11 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈11

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 11

    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 business meaning, no approving a metric/mapping.

    line 100
  2. Very specific:

    MUST NOT grant approval or move a readiness stage to pass (named-human / Core Authority only).

    line 101
  3. Distinctive:

    MUST NOT connect to a DB or external service, and MUST NOT publish a Power BI artifact (those are Execution Adapter capabilities -- F016 …

    line 103
  4. Distinctive:

    MUST NOT emit a numeric / maturity / confidence score (hard rule #9), and MUST NOT emit a completeness count (Clarifications 2026-06-25).

    line 105
  5. Very specific:

    When a required Core Authority input is absent or a stage is not yet pass, the module SURFACES it as a blocker and stops -- it never …

    line 110
  6. Distinctive:

    Composes, never invents: Every section is a SUMMARY or REFERENCE of an existing committed artifact.

    line 120
  7. Very specific:

    Reads only committed artifacts: No live database, no PBIP model, no Power BI execution adapter (F016), no publish/deploy.

    line 136
  8. Very specific:

    Generic: No worked-example specifics (billing codes, segments, PII column names, per-table grain keys).

    line 147
  9. Distinctive:

    No numeric confidence/health score and no completeness count anywhere.

    line 182
  10. Very specific:

    Read mappings/<table>/readiness-status.yaml -- current_stage, per-stage status, approvals[], blocking_reasons[].

    line 187
  11. Very specific:

    Stop at the composition boundary.

    line 217
  12. Very specific:

    After a run, git status shows the only new/modified files are the two derived pack files under mappings/<table>/ (evidence-pack-index.md, …

    line 256
  13. Very specific:

    No source artifact is modified, readiness-status.yaml / approvals[] is unchanged, and no stage moved to pass.

    line 258
  14. Distinctive:

    Do NOT invent or fabricate any section's content when its source is missing.

    line 264
  15. Very specific:

    Do NOT write, grant, or imply a publish approval.

    line 265
  16. Distinctive:

    Do NOT edit, re-author, or redefine any source artifact (including the F013 handoff).

    line 267
  17. Distinctive:

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

    line 268
  18. Distinctive:

    Do NOT read a live database or PBIP model.

    line 269
  19. Very specific:

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

    line 271
  20. Distinctive:

    Do NOT silently reconcile disagreeing sources or choose a winner (Principle V).

    line 272
  21. Distinctive:

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

    line 273
  22. Very specific:

    When a table is driven end-to-end, the retail-orchestrate conductor may invoke this generator at the late stages (Semantic Model Ready …

    line 295

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

evidence-pack-generator

  • Roadmap feature: F028 On-disk spec: specs/022-evidence-pack-generator/ (dir 022 == F028; 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).

By the time a table reaches the late readiness stages its evidence is real but SCATTERED across a dozen artifacts. A reviewer about to authorize publish has no single legible place to SEE it all at once, with each claim traceable to its source. This skill is the COMPOSER that assembles those scattered, already-committed artifacts into one ordered pack of 10 fixed sections. It FILLS the bundle; it does not originate the evidence and it owns no truth. Every section points back at the artifact it summarizes; any section whose source is missing or unfilled is recorded as a BLOCKER, never papered over with invented content. The pack surfaces the publish-ready decision; it never makes it.

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 a committed artifact from committed evidence" (the pack), and -- per the matrix -- MAY write derived evidence but MUST NOT execute.

The filled templates/module-contract.md declaration follows.


Module Contract -- Evidence Pack Generator

  • 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 F013 BI handoff pack)
  • Roadmap feature: F028 On-disk spec: specs/022-evidence-pack-generator/
  • Owner: data-owner / governance reviewer
  • Status: Authored (docs/templates; no runtime code -- the agent is the runtime)

What it does (one line)

Composes the already-committed late-stage evidence (10 sections across source -> publish) into one ordered, readable pack, links every section to its source, and surfaces the recorded publish_ready state -- inventing nothing.

Core Authority it READS

It reads; it never writes these.

  • mappings/<table>/readiness-status.yaml -- current_stage, per-stage status, approvals[], blocking_reasons[] (the publish_ready state + recorded approval the summary surfaces).
  • The 10 committed section sources (see the section contract below): source-profile, source-map.yaml, assumptions.md / unresolved-questions.md / ADRs, the mappings/<table>/metrics/ contracts, the recorded seshat check / retail validate results + F012 roll-up, the F010 semantic-model summary, the F011/F011A dashboard design, the FILLED F013 handoff pack, data-issues.md, and the F015 reconciliation ledger (+ F014 drift).

Derived evidence it WRITES

Composed FROM committed evidence; never a new approval, metric definition, or stage change.

  • mappings/<table>/evidence-pack-index.md -- the ordered 10-section index (a filled copy of templates/evidence-pack-index.md).
  • mappings/<table>/evidence-pack-summary.md -- the one-page readiness summary (a filled copy of templates/evidence-pack-summary.md).

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 business meaning, no approving a metric/mapping.
  • MUST NOT grant approval or move a readiness stage to pass (named-human / Core Authority only).
  • MUST NOT connect to a DB or external service, and MUST NOT publish a Power BI artifact (those are Execution Adapter capabilities -- F016 owns publish).
  • MUST NOT emit a numeric / maturity / confidence score (hard rule #9), and MUST NOT emit a completeness count (Clarifications 2026-06-25).

How it handles a missing input

When a required Core Authority input is absent or a stage is not yet pass, the module SURFACES it as a blocker and stops -- it never fabricates the input, self-approves, or proceeds past the missing gate (Principle V; stop-and-ask). A missing/unfilled/blank-template section source -> that section is blocked with a blocking_reasons[] entry naming the missing source.


Scope boundary (read first)

  • Composes, never invents. Every section is a SUMMARY or REFERENCE of an existing committed artifact. It adds no data, metric, decision, or number the source does not contain. A section whose source is missing/unfilled/blank-template is recorded as a blocked status with a blocker naming the missing source -- never fabricated.
  • Surfaces, never asserts (publish). The summary SURFACES the publish_ready status and the recorded approval (owner + date) READ from readiness-status.yaml. It DISPLAYS a value it read from Core Authority and records nothing back: it never writes an approval, never edits approvals[], never moves a stage to pass. It prints a publish-ready CLAIM only when publish_ready: pass with a named approval is recorded. (This is the F028 boundary: it reads-and-displays the decision -- it does NOT transcribe a fresh decision and it does NOT make one.)
  • Consumes F013, never redefines it. Section 08 references/embeds the table's FILLED templates/handoff/bi-handoff-pack.md instance and links to it. F028 never edits that instance, never re-authors the F013 template, and never records the publish approval (F013 / Core Authority owns that). If the handoff is missing or incomplete, section 08 is a BLOCKER -- no substitute handoff is synthesized.
  • Reads only committed artifacts. No live database, no PBIP model, no Power BI execution adapter (F016), no publish/deploy. Any live signal must already be recorded as committed evidence (e.g. by retail validate) before the pack can cite it.
  • Adds no gate. It runs no new validator, adds no seshat check rule, defines no new readiness stage. It composes results other tools already recorded.
  • No fake confidence, no count. Readiness is the four explicit statuses (not_started / blocked / warning / pass) + evidence[] + blocking_reasons[]. No numeric confidence/health score anywhere (hard rule #9); no "N of 10 sections present" tally (the four-status per-section record plus the rolled-up blockers convey completeness -- Clarifications 2026-06-25).
  • Generic. No worked-example specifics (billing codes, segments, PII column names, per-table grain keys). C086 is a cited filled instance, never baked in (Principle VII). ASCII only, UTF-8 no BOM; short repo-relative paths (Windows MAX_PATH).

The 10-section contract (fixed, ordered) and its committed source map

The section list and order are a stable contract so packs are comparable across tables. Each section is COMPOSED from the committed source on its right and links back to that source's repo-relative path.

#SectionComposed from (committed source)
01source-profilethe table's source-profile.md (Source Ready)
02source-map-summarysource-map.yaml (the Principle-IV mapping-gate artifact; F008 consumes it, does not produce it)
03assumptions-and-decisionsassumptions.md + unresolved-questions.md + relevant ADRs
04metric-contractsmappings/<table>/metrics/ filled contracts (F009/F010)
05validation-summaryrecorded seshat check + retail validate results + the F012 data-quality roll-up
06semantic-model-summaryF010 / retail semantic check recorded output
07dashboard-summaryF011 dashboard design + F011A visual foundation
08handoff-packthe table's FILLED F013 templates/handoff/bi-handoff-pack.md instance (EMBED / reference; never re-authored)
09known-limitationsdata-issues.md + recorded caveats
10release-notesF015 reconciliation ledger (+ F014 drift signals + readiness-status.yaml approvals[])

Even release notes (10) COMPOSE existing evidence -- they never invent.

Per-section record shape

Each section row carries: section id + title; status (one of not_started / blocked / warning / pass); source artifact path(s); evidence[]; blocking_reasons[]; and a one-line summary. Rules:

  • A missing / unfilled / blank-template source -> status: blocked + a blocking_reasons[] entry naming the missing source. NO fabricated content.
  • A source that exists but is warning upstream -> the section carries that warning verbatim; it does NOT auto-promote to pass.
  • No numeric confidence/health score and no completeness count anywhere.

Procedure (numbered; do not reorder)

1. Resolve the table and read the state

Read mappings/<table>/readiness-status.yaml -- current_stage, per-stage status, approvals[], blocking_reasons[]. This is read-only; it fixes the current stage the summary states and the publish_ready state the summary surfaces.

2. Compose the 10 sections in fixed order

For each section 01..10, locate its committed source (the map above). If the source exists and is FILLED, compose a one-line summary and record the section path + status

  • evidence. If the source is missing / unfilled / a blank template, record the section blocked with a blocker naming the missing source -- do NOT synthesize content. Carry any upstream warning verbatim; never auto-promote it.

3. Embed F013 as section 08 (consume, never redefine)

Reference / embed the table's FILLED mappings/<table>/handoff/bi-handoff-pack.md instance and link to it. Never edit it, never re-author the F013 template, never record the publish approval. If it is missing or incomplete, section 08 is a blocker.

4. Render the index

Render templates/evidence-pack-index.md filled: one row per section with id+title, status, source path(s), evidence, blockers, one-line summary. Every present section resolves to a real committed artifact path; every absent one resolves to a recorded blocker. No section originates from nothing.

5. Render the summary (surface, never assert)

Render templates/evidence-pack-summary.md filled: the current readiness stage; the publish_ready status SURFACED from readiness-status.yaml; the recorded approval (owner + date) when publish_ready: pass; the rolled-up open blockers across sections; and an explicit "in-progress" marker when composed before Publish Ready. Print a publish-ready CLAIM ONLY when publish_ready: pass + a named recorded approval exist.

6. STOP

Stop at the composition boundary. The skill wrote only the derived index + summary under mappings/<table>/. It wrote no approval, moved no stage to pass, and edited no source artifact (including the F013 handoff). Any judgment call -- publish authorization, a source disagreement, a grain/PII/sentinel ambiguity surfaced in the pack -- is a stop-and-ask for the named human (Principle V).

In-progress posture (US4)

The pack is composable from Semantic Model Ready (stage 5) onward, not only at the final gate. When composed early: present sections render and link; absent downstream sections (e.g. 07 dashboard, 08 handoff) are recorded as blockers; the summary states the table's CURRENT stage honestly and claims no stage the table has not reached. An in-progress pack NEVER prints a publish-ready claim (the US3 guardrail is not weakened by the US4 posture).

Surface, never assert -- the publish-ready guardrail (US3)

Read state in readiness-status.yamlWhat the summary does
publish_ready: pass + a named approval in approvals[]surfaces the recorded approval (owner + date), cites readiness-status.yaml as the source, MAY state publish-ready
publish_ready is anything else (not_started / blocked / warning)shows publish-ready as that status with the upstream blocking reasons -- MUST NOT print a publish-ready claim

In every case the generator has written NO approval, moved NO stage to pass, and edited NO source artifact -- it only wrote the derived pack. The decision belongs to the named human via Core Authority; the pack reads-and-displays it.

Honest-state rules (never invent, never silently reconcile)

SituationWhat the generator does
A section source is missing / unfilledrecord that section blocked with a blocker naming the source; the summary cannot read "complete"; no substitute content
A source exists but is the blank template, not a filled instancetreat as missing -> blocked; do not summarize placeholder text as real evidence
F013 handoff (section 08) is incompleterecord section 08 a blocker; do not synthesize a substitute handoff or re-author F013's template
Two upstream sources disagree (e.g. a contract count differs between the metric store and the semantic-model summary)surface BOTH with their source links and record the discrepancy as a warning for human resolution (Principle V); do NOT pick a winner or reconcile silently
A numeric confidence/health score (or an "N of 10" count) is requestedrefuse; return the four explicit statuses + evidence + blockers (hard rule #9; Clarifications 2026-06-25)
Live data or a PBIP model is requested as a section sourceout of scope; the generator reads only committed artifacts

Composes-only proof

After a run, git status shows the only new/modified files are the two derived pack files under mappings/<table>/ (evidence-pack-index.md, evidence-pack-summary.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.
  • Do NOT write, grant, or imply a publish approval; do NOT move any readiness stage to pass; do NOT edit approvals[].
  • Do NOT edit, re-author, or redefine any source artifact (including the F013 handoff).
  • Do NOT emit a numeric confidence / health score or a completeness count.
  • Do NOT read a live database or PBIP model; do NOT call the Power BI execution adapter (F016); do NOT publish / deploy.
  • Do NOT add a seshat check rule, define a new readiness stage, or alter a gate.
  • Do NOT silently reconcile disagreeing sources or choose a winner (Principle V).
  • Do NOT inline C086 / retail_store_sales specifics into the pack, the templates, or the doc.

See also

  • The tool doc (10-section contract + source map + ops + F013 delta): ../../../docs/tools/evidence-pack-generator.md.
  • The output shapes: ../../../templates/evidence-pack-index.md, ../../../templates/evidence-pack-summary.md.
  • The F013 handoff it consumes as section 08: ../../../templates/handoff/bi-handoff-pack.md (scope delta: F028 consumes F013, never redefines it).
  • The four-status / no-fake-confidence model: ../../../docs/readiness/readiness-model.md; the publish stage authority: ../../../docs/readiness/publish-ready.md.
  • The authority contract: ../../../docs/architecture/product-modules.md (the five categories + the matrix + the two sub-vocabularies), ../../../docs/architecture/core-vs-modules-and-adapters.md (the prose + the seam), ../../../templates/module-contract.md (the copy-me declaration filled above).
  • The spec: ../../../specs/022-evidence-pack-generator/spec.md. It cites a filled worked example under ../../../docs/worked-examples/.

Orchestration

When a table is driven end-to-end, the retail-orchestrate conductor may invoke this generator at the late stages (Semantic Model Ready onward) to compose the evidence pack for the data-owner review. This skill stays single-purpose: it composes the pack, records per-section status + blockers, surfaces (never asserts) the publish state, and STOPS at the human approval boundary. Advancing a stage, clearing a blocker, and recording the publish approval live in the per-table owner / 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.