agentleFS
KemetraKemetra/Seshat-BI/.claude/skills/readiness-viewer/SKILL.md

readiness-viewer

Skill2 starsChanged 4 months agoApache-2.0View on GitHub

Show the stage-centric readiness lens across the kit's sources / tables / reports -- one per-stage status MATRIX over the seven readiness stages, each stage's evidence rendered as NAVIGABLE REFERENCES, and an approvals TIMELINE, read from each item's readiness-status.yaml. Use when someone asks "show the readiness viewer", "which stage is each table at", "what evidence backs Gold Ready", or "who approved this gate, and when". READ-ONLY and invoke-and-present only: it RENDERS the recorded state (it never recomputes a status, advances a stage, writes a pass, infers/back-fills an approval, or fabricates evidence), it runs NO validator and opens NO DB connection, and it emits NO numeric health / confidence / percent-ready score (hard rule #9). It is the stage-lens sibling of the F012 control room: same inputs, different view.

The file

We split this skill into the rules it gives an agent

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

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈6

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 5

    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 66
  2. Very specific:

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

    line 67
  3. Distinctive:

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

    line 69
  4. Distinctive:

    MUST NOT emit a numeric / maturity / confidence score (hard rule #9).

    line 71
  5. Distinctive:

    When a required Core Authority input is absent, the viewer SURFACES it as a flag and renders the gap as a gap -- it never fabricates the …

    line 77
  6. Very specific:

    Renders, never re-derives: Every cell is a value copied from the source: a per-stage status is shown EXACTLY as readiness-status.yaml …

    line 87
  7. Very specific:

    Shows missing evidence AS MISSING: When a stage's evidence[] is empty or a referenced file is absent, it renders "evidence missing" / …

    line 97
  8. Distinctive:

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

    line 105
  9. Distinctive:

    Every rendered element traces back to a recorded field -- a re-render, not a measurement.

    line 147
  10. Very specific:

    If asked for "one readiness score", "a percent-ready per item", or "a confidence number", DECLINE: cite docs/readiness/readiness-model.md …

    line 218
  11. Very specific:

    When items are driven end-to-end, the retail-orchestrate conductor may invoke the viewer as the stage-progression READ after sequencing an …

    line 269

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 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

readiness-viewer

The F012 control room answers "what is broken, how badly, worst-first". The Readiness Viewer answers a different question over the SAME inputs: "which of the seven stages has each item reached, with what evidence, and who approved the gate that let it advance". It is a read-only stage-progression LENS over evidence that already exists per item -- it introduces no new validator and no new gate (roadmap rule #8; Principle VIII). It renders, then STOPS.

Module contract (this skill IS a filled Product Module declaration)

This skill declares its authority category up front, per the F024 Companion Tools Architecture contract (templates/module-contract.md).

  • Authority category: Product Module
  • Capability level: read-only (exactly one)
  • Product layer: 4 (the functional axis -- see docs/roadmap/roadmap.md; orthogonal to category; matches the F012 control-room sibling)
  • Roadmap feature: F026 On-disk spec: specs/020-readiness-viewer/ (roadmap F-number is authoritative when the two disagree)
  • Owner: the readiness / data-quality lead (a named role -- never "the agent")
  • Status: Authored

What it does (one line)

Reads each item's readiness-status.yaml (Core Authority) and presents the seven-stage status matrix, each stage's evidence[] as navigable references, and the approvals[] timeline -- creating no truth.

Core Authority it READS

It reads these committed truth artifacts; it never writes them.

  • mappings/<item>/readiness-status.yaml -- current_stage, per-stage status (the four words), evidence[], blocking_reasons[], approvals[], next_action.
  • the files each evidence[] entry references (to mark a reference "referenced file not found" when absent -- it reads them only to check existence, never edits).
  • the "Required owner / approval" field of each docs/readiness/<stage>-ready.md (to know which gates require an approval before flagging a missing one).

Derived evidence it WRITES

  • none (read-only). A read-only module writes NOTHING -- no cache, no report, no per-item file.

Approved step it EXECUTES

  • none (read-only). It executes no step; it renders recorded state.

Forbidden operations (the matrix says NO)

  • 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).
  • MUST NOT emit a numeric / maturity / confidence score (hard rule #9).
  • As a read-only module it additionally MUST NOT write any derived evidence or execute any step.

How it handles a missing input

When a required Core Authority input is absent, the viewer SURFACES it as a flag and renders the gap as a gap -- it never fabricates the input, self-approves, or reads a missing-evidence stage as complete (Principle V; stop-and-ask).

  • missing readiness-status.yaml -> the item's row is "no readiness file" (FR-009); a stage with empty evidence[] -> "evidence missing"; a pass gate whose required approval is absent -> "approval not recorded" -- never auto-resolved.

Scope boundary (read first)

  • Renders, never re-derives. Every cell is a value copied from the source: a per-stage status is shown EXACTLY as readiness-status.yaml records it. If the file says a stage is pass, the viewer shows pass; it never decides pass itself. Core Authority owns truth.
  • Read-only. It never edits a readiness-status.yaml or any per-item artifact, never advances a stage, never writes a pass, never runs SQL, never opens a DB connection, never runs seshat check / retail validate as a new check.
  • Infers no approval. It RENDERS recorded approvals[] (each a named owner + date already written by the approving human); it never establishes, fabricates, or back-fills an approval, and never treats an unapproved gate as approved.
  • Shows missing evidence AS MISSING. When a stage's evidence[] is empty or a referenced file is absent, it renders "evidence missing" / "referenced file not found" -- it never invents a reference and never lets a missing-evidence stage read as complete.
  • No fake confidence. Readiness is the four explicit statuses + evidence + blockers. The viewer MUST NOT emit a numeric health / confidence / percent-ready score (hard rule #9). A score is OPTIONAL and DEFERRED; the viewer is not where one appears.
  • Generic. No worked-example specifics (billing codes, segments, PII column names, per-table grain keys). C086 / retail_store_sales are filled instances cited as references, never baked in (Principle VII).
  • ASCII only, UTF-8 no BOM. The stage spine is written Source Ready -> ... -> Publish Ready (ASCII ->); every dash is --.

Relationship to F012 (same inputs, different lens)

F012 (Data Quality Control Room, shipped, skill .claude/skills/retail-control-room/) is already a read-only cross-table roll-up of findings + blockers, worst-first, reading the SAME per-item readiness-status.yaml. F026 must be the DELTA, not a re-spec.

Both modules read the SAME Core Authority files; F026 introduces NO new input, NO new measurement, and NO new pipeline. The difference is the lens:

DimensionF012 Control Room (shipped)F026 Readiness Viewer (this skill)
Organizing question"What is broken, how badly, worst-first?""Which of the 7 stages has each item reached, with what evidence and approvals?"
Stage renderingcurrent_stage + its one status, worst-firsta per-stage MATRIX across all 7 stages
evidence[] renderingsummarized as MEASURED COUNTSrendered as NAVIGABLE REFERENCES (path/line per stage)
approvals[] renderingnot read by F012rendered as a chronological TIMELINE
Primary axisseverity (findings + blockers, descending)the stage spine (Source Ready .. Publish Ready)
next_actionalready surfacedalso surfaced (SHARED, NOT a delta)

The three genuine deltas are exactly: (1) the per-stage status matrix across all seven stages, (2) evidence[] rendered as references rather than counts, and (3) the approvals[] timeline (F012 does not read approvals[]). next_action is SHARED with F012 and is NOT a delta.

Chosen shape: (a). This ships as a SEPARATE readiness-viewer skill that REUSES F012's existing read-fan-out over the per-item files (one aggregation, two lenses) -- not a re-implemented scan. The merge fallback (b) is explicit: if the three deltas ever reduce so that the only durable difference is sort order + column labels, this should NOT ship as a separate module -- it should fold into F012 as an optional stage-view section. Shape (a) holds because the stage matrix reveals WHERE in the seven-stage progression an item sits, evidence-as-reference lets a reviewer OPEN the backing file, and the approvals timeline answers "who let this advance, when" -- each gives a reader something the control room cannot.

Renders, never re-derives (the evidence chain)

Every rendered element traces back to a recorded field -- a re-render, not a measurement. A rendered value with no traceable source is a defect.

Rendered elementSource field it copies VERBATIM
each matrix cell (per-stage status)readiness-status.yaml stages.<stage>.status
the marked current stagereadiness-status.yaml current_stage
the single next actionreadiness-status.yaml next_action
each evidence referencereadiness-status.yaml stages.<stage>.evidence[] (each entry as-recorded)
each timeline approvalreadiness-status.yaml approvals[] ({stage, owner, at})
which gates require an approvaldocs/readiness/<stage>-ready.md "Required owner / approval"

Run it -- produce the stage-centric view

Render templates/readiness-view.md filled from the per-item evidence, reusing F012's read-fan-out for discovery.

1. The seven-stage status matrix (the MVP)

Discover items exactly as F012 does: scan each mappings/<item>/ directory for a readiness-status.yaml (ADR 0004 canonical location); emit one matrix row per discovered file. Add NO second discovery path and invent NO row for an item with no file. For each item, emit a row x seven stage columns (Source Ready -> Mapping Ready -> Silver Ready -> Gold Ready -> Semantic Model Ready -> Dashboard Ready -> Publish Ready); each cell is the stages.<stage>.status copied VERBATIM (one of not_started / blocked / warning / pass). Mark current_stage. Show the single next_action. Never recompute or upgrade a status -- a stage the file records as not_started shows not_started.

2. Evidence rendered as navigable references

For each stage, render every evidence[] entry as its committed reference, copied VERBATIM: if the entry carries a line/section anchor, render it with that anchor; if it is a bare committed path, render the bare path. NEVER synthesize a line number or section anchor the source does not record (that is fabricated evidence). A stage with empty evidence[] renders "evidence missing" and NAMES the expected artifact; a pass stage with empty evidence[] renders "evidence missing for a pass stage" as an explicit flag (a pass without evidence is surfaced, never hidden). An evidence[] entry whose referenced file is absent on disk renders the reference marked "referenced file not found" -- the entry is never dropped and never replaced with an invented one.

3. The approvals timeline

Render approvals[] as a chronological timeline: each approval as {stage/gate, named owner, date} in date order, copied VERBATIM. Flag a pass gate "approval not recorded" ONLY when BOTH conditions hold: (a) that stage's docs/readiness/<stage>-ready.md "Required owner / approval" field declares an approver IS required, AND (b) no matching approvals[] entry exists. Where the stage doc records NO required approver (e.g. a mechanical gate whose doc reads "None -- mechanical ... No human approval is added at this stage"), an empty approvals[] is NORMAL and MUST NOT be flagged. The viewer reads the requirement from the stage doc; it NEVER decides the requirement itself and NEVER infers, establishes, or back-fills an approver (no-self-approval; Principle V).

4. Surface conflicts (never resolve them)

Surface, as explicit flags, never reconciled: current_stage disagreeing with the per-stage statuses (e.g. current_stage: gold_ready but Silver Ready recorded blocked); a pass stage with empty evidence[]; an approval that references a stage the matrix shows as not_started. The viewer is a lens, not an arbiter -- it does NOT resolve a conflict by picking one side.

5. Traceability

For every rendered value, be able to name the exact committed source path (and line/section where the source records it). If asked "where does this come from", answer with the path -- not a recomputation.

No fake confidence (the guardrail)

If asked for "one readiness score", "a percent-ready per item", or "a confidence number", DECLINE: cite docs/readiness/readiness-model.md "No fake confidence (the scoring rule)" -- readiness is explicit status + evidence + blockers, not a confidence score -- and return the four explicit statuses across the seven stages instead. A stage matrix is exactly where a tidy invented score is tempting; it is forbidden (hard rule #9). Any future optional score is DEFERRED until scoring rules exist in the readiness model.

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

SituationWhat the viewer does
Zero items with a readiness filerender an empty matrix + a clear "no items onboarded yet" note; do not error, do not invent rows
A readiness-status.yaml malformed / partialshow that item "readiness file incomplete: <file>" for the affected fields; do NOT guess the missing stage statuses or evidence (FR-009)
current_stage disagrees with per-stage statusesSURFACE the conflict as a flag; do NOT resolve it by picking one (Principle V)
A stage is pass with empty evidence[]surfaced as "pass without evidence", an explicit flag; never hidden
An approval references a not_started stageshown as a conflict flag; the stray approval is not reconciled or deleted
A pass gate whose stage doc requires an approver, with no matching approvals[] entryflagged "approval not recorded"; an approver is NEVER inferred

Read-only proof

The skill modifies nothing: after a run, git status shows zero modified mappings/<item>/readiness-status.yaml or per-item artifact, and zero approvals[] entries added by the viewer. It triggers no state-mutating seshat check / retail validate run of its own.

See also

  • The output shape: templates/readiness-view.md; the usage + boundary doc: docs/tools/readiness-viewer.md.
  • The headline overlap it is the delta of (F012): the skill .claude/skills/retail-control-room/SKILL.md, the template templates/data-quality-control-room.md.
  • The Core Authority input it renders: templates/readiness-status.yaml (current_stage, per-stage status, evidence[], blocking_reasons[], approvals[], next_action); ADR 0004 (canonical mappings/<table>/readiness-status.yaml location).
  • The module category + read-only contract: docs/architecture/product-modules.md, docs/architecture/core-vs-modules-and-adapters.md, templates/module-contract.md (F024 Companion Tools Architecture, specs/018-companion-tools-architecture/).
  • The model + no-fake-confidence rule: docs/readiness/readiness-model.md; the stage sequence: docs/readiness/readiness-pipeline.md; the "Required owner / approval" field per stage: docs/readiness/<stage>-ready.md.
  • The roadmap row + hard rules: docs/roadmap/roadmap.md (F026; rules #7/#8/#9); Principles V, VII, VIII, IX. retail_store_sales is a cited filled instance: docs/worked-examples/retail-store-sales.md (a filled worked example under docs/worked-examples/).

Orchestration

When items are driven end-to-end, the retail-orchestrate conductor may invoke the viewer as the stage-progression READ after sequencing an item -- to see where the item sits across all seven stages, what backs each gate, and who approved it. This skill reads state and reports; it advances no stage and clears no blocker. Moving a stage to pass, recording an approval, and clearing a blocker all remain Core Authority actions by the named owner, never the viewer (Principle V; no-self-approval).

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.