agentleFS
KemetraKemetra/Seshat-BI/.claude/skills/retail-onboard-table/SKILL.md

retail-onboard-table

Skill2 starsChanged 4 months agoApache-2.0View on GitHub

Walk a NEW raw retail table across the FIRST readiness transition -- Source Ready (Stage 1) through Mapping Ready (Stage 2) -- and seed its per-table readiness-status, in the Seshat BI repo. Use when someone says "onboard <schema>.<table>", "take this new table from nothing to a reviewed map", or "start the readiness journey for a table". This is the stage-transition FRONT DOOR: it sequences profile -> map -> gate, writes the readiness-status record, and STOPS at Mapping Ready. It DELEGATES the five mapping artifacts to the `source-mapping` skill (it does not re-implement mapping); it NEVER writes `silver.*` SQL, NEVER self-grants the gate approval, and NEVER answers a Principle-V judgment call (grain, PII, business rollup, product identity).

  • Reads credentials
  • Installs packages

The file

We split this skill into the rules it gives an agent

7 rules. About 0 are common, 2 are distinctive, and 5 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.

  • 5

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Do NOT duplicate the mapping procedure -- it lives in source-mapping.

    line 94
  2. Very specific:

    Every pass MUST carry evidence[].

    line 109
  3. Distinctive:

    Conflicting answer rule: if an analyst answer contradicts a profiled data fact, surface the conflict and STOP to reconcile -- do not …

    line 125
  4. Very specific:

    When the artifacts are authored and the gate is OPEN (review pending): emit the reconciliation blank, set mapping_ready: blocked, state the …

    line 130
  5. Distinctive:

    STOP. The wizard never authors silver.

    line 137
  6. Very specific:

    If no DSN is configured or the db extra is absent: do NOT traceback and do NOT fabricate profile numbers.

    line 141
  7. Very specific:

    When a table is driven end-to-end, the retail-orchestrate conductor invokes this wizard as its Source -> Mapping leg (Phases 1-4).

    line 170

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

retail-onboard-table

The onboarding front door for ONE table's first two readiness stages. The kit already ships the verb that authors the mapping artifacts (source-mapping) and the conductor that sequences every verb end-to-end (retail-orchestrate). This skill is the stage-scoped composition between them: "I have a new raw table -- walk me from nothing to a reviewed map." It advances Source Ready -> Mapping Ready, seeds the per-table readiness-status.yaml, and STOPS. It is a procedure the agent performs (agent-first, Principle I); seshat check and the read-only profile are gates it CALLS, not a CLI subcommand.

Scope boundary (read first)

  • Agent-first, no CLI. This is a SKILL the agent runs; it adds no retail subcommand and no Python.
  • ENTERS at Source Ready, EXITS at Mapping Ready. The terminal state is Mapping Ready -- the three gate artifacts committed and either mapping_ready: blocked (review pending, the common case) or mapping_ready: pass (only after a HUMAN has recorded approval). Both are successful wizard runs.
  • NEVER crosses into Silver Ready (Principle IV, roadmap rule #2). It writes no silver.* SQL, no migration, and never calls retail-build-warehouse. Its last action is to seed/update the readiness-status, state the next allowed action, and STOP.
  • NEVER self-grants approval or invents a judgment call (Principle V). The four reserved seams -- grain, PII publish-safety, business rollup/segment, product identity -- are PROPOSED with a data fact and raised as unresolved-questions.md rows; the wizard stops there.
  • No fake confidence. Readiness is the four explicit statuses (not_started | blocked | warning | pass) + evidence[] + blocking_reasons[]. No numeric score (roadmap rule #9).
  • Delegates mapping; does not duplicate it. Stage 2 invokes source-mapping to author the five artifacts. This skill owns the WALK and the readiness bookkeeping, not the mapping procedure.
  • ASCII only, UTF-8 no BOM (-> arrows, '' OR NULL).

Run-state: read mappings/<table>/ FIRST (no new state file)

Compute the current stage from what is already on disk -- there is NO onboarding state file to create (mirrors retail-orchestrate's run-state rule):

What you observeCurrent stage / action
No mappings/<table>/ dirStart at Stage 1 (profile).
source-profile.md present, no source-map.yamlResume at Stage 2 (delegate to source-mapping).
The five artifacts present, unresolved-questions.md shows Gate status: OPEN (or open rows)STOPPED at the gate -- report the open questions; do not overwrite, do not advance.
Gate status: CLEARED, zero open rows, an approvals[] entry recordedMapping Ready reached -- promote mapping_ready: pass; state Silver Ready is the next (out-of-scope) stage; STOP.

Resume from the first incomplete artifact; NEVER clobber a committed (reviewed) one. You may READ Gate status; you may NOT write CLEARED yourself (that is the reviewer's action).

Stage 1 -- Source Ready (profile + PROPOSE semantics)

Drive the mechanical profile over a READ-ONLY connection and record into mappings/<table>/source-profile.md (definition-of-done = source-ready.md pass):

  • row count + column count;
  • per-column missingness measured as '' OR NULL (never IS NULL alone -- RC5);
  • candidate-key uniqueness proof (does the proposed PK hold on the data?);
  • returns-column population.

Semantic rows (what each column MEANS) are PROPOSED for human confirmation, never invented. Record source_ready: pass with source-profile.md as evidence when the mechanical numbers are measured; warning in deferred-boundary mode (below); or blocked with the concrete reason if a required number is unmeasurable -- and then do NOT enter Stage 2 (no mapping on an unprofiled source).

Stage 2 -- Mapping Ready (delegate to source-mapping)

Invoke the source-mapping skill to author the five artifacts under mappings/<table>/ (definition-of-done = mapping-ready.md's artifact set):

  • source-map.yaml -- grain, PK, every column's pii: flag, gold placement;
  • assumptions.md -- RC1-RC16 adopted/deviated, each deviation citing a data fact;
  • unresolved-questions.md -- the open judgment calls (Gate status: OPEN until a human clears it);
  • the reconciliation-report.md blank (the live-acceptance run, filled later).

Do NOT duplicate the mapping procedure -- it lives in source-mapping. The wizard sequences the call and then does the readiness bookkeeping below.

Readiness-status bookkeeping

Seed/update the per-table status from the readiness-status template at the canonical mappings/<table>/readiness-status.yaml (ADR 0004 -- co-located with the mapping artifacts, spans all seven stages). The wizard is the FIRST writer of this file. Set:

  • source_ready: pass (mechanical numbers measured) / warning (deferred mode) / blocked (unmeasurable) -- with evidence[] or blocking_reasons[];
  • mapping_ready: blocked (review pending) until a human records approval;
  • current_stage, next_action, last_checked_at, checked_by.

Every pass MUST carry evidence[]; every blocked MUST carry blocking_reasons[]; emit NO numeric confidence score.

Human seams -- HARD-STOP (Principle V; the wizard proposes, a human decides)

Each is a judgment call the agent cannot settle from data alone. PROPOSE it with the supporting data fact, raise an unresolved-questions.md row with a NAMED owner, set the matching blocking_reasons[], and STOP -- NEVER satisfiable by a silent default:

SeamTriggerPropose (with data fact)Owner
Graincandidate PK not unique on the rowsreport the duplicate count; propose the finer grain / composite PK -- never collapse or pick silentlyanalyst
PII publish-safetya pii:true candidate columnpropose the default (drop before the BI layer, RC4); raise the publish-safety questiongovernance
Business rollup / segmenta categorical needing a value->group mappingNEVER invent the mapping; raise it for the analyst-supplied table; default unmapped -> UNMAPPEDanalyst
Product identitywhich column authoritatively identifies the entity (or two columns disagree)report the conflict; never assert identityanalyst / data owner

Conflicting answer rule: if an analyst answer contradicts a profiled data fact, surface the conflict and STOP to reconcile -- do not proceed (evidence-cross-check).

Terminal: Mapping Ready -- STOP

When the artifacts are authored and the gate is OPEN (review pending): emit the reconciliation blank, set mapping_ready: blocked, state the SINGLE next allowed action ("human review + approval of the map"), and explicitly confirm the wizard wrote NO silver.* and self-granted NO approval. When Gate status: CLEARED + approvals[] already exist (a human approved): promote mapping_ready: pass (evidence = the artifacts + the approval), state "Mapping Ready reached; the next stage is Silver Ready / retail-build-warehouse -- OUT of this wizard's scope", and STOP. The wizard never authors silver.

Deferred-boundary mode (no DSN or no db extra)

If no DSN is configured or the db extra is absent: do NOT traceback and do NOT fabricate profile numbers. Mark the mechanical rows [PENDING LIVE PROFILE], record source_ready: warning (never pass), and print the enable steps: pipx inject seshat-bi psycopg2-binary (or pip install "seshat-bi[db]"), then set DATABASE_URL (or ANALYTICS_DB_*) in the git-ignored .env -- never commit a real DSN. The semantic stop-and-ask and the gate stop still run (they need no DB).

Generic, not C086

This skill and the onboarding checklist are GENERIC (roadmap rule 7). No C086/pharmacy specifics (billing codes, segment rollups, PII column names, pharmacy grain keys) appear here -- placeholders only. A worked example is CITED as a filled instance (see the filled worked examples), never copied.

See also

  • The two stages spanned: the Source Ready and Mapping Ready definitions.
  • The reviewable definition-of-done: the onboarding checklist.
  • The spine + state model: the readiness model and readiness pipeline, plus the readiness-status template.
  • The delegated mapping leg: the source-mapping skill.
  • The downstream build verb (out of scope here): the retail-build-warehouse skill.
  • The roadmap row: F006, Layers 1-2, Source -> Mapping.
  • Principles: constitution I, IV, V, VII, VIII, IX.

Orchestration

When a table is driven end-to-end, the retail-orchestrate conductor invokes this wizard as its Source -> Mapping leg (Phases 1-4). This skill does that leg and STOPS at Mapping Ready; the cross-table self-heal loop (run gate -> classify -> auto-fix mechanical / HARD-STOP judgment calls -> re-run) lives ONLY in retail-orchestrate, never here. Mapping-gate approval is the reviewer's action; no loop self-grants it.

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.