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
In this repository60 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- approval-consoleSkill
- approval-evidence-packSkill
- 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-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
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
- Very specific: line 94
Do NOT duplicate the mapping procedure -- it lives in source-mapping.
- Very specific: line 109
Every pass MUST carry evidence[].
- Distinctive: line 125
Conflicting answer rule: if an analyst answer contradicts a profiled data fact, surface the conflict and STOP to reconcile -- do not …
- Very specific: line 130
When the artifacts are authored and the gate is OPEN (review pending): emit the reconciliation blank, set mapping_ready: blocked, state the …
- Distinctive: line 137
STOP. The wizard never authors silver.
- Very specific: line 141
If no DSN is configured or the db extra is absent: do NOT traceback and do NOT fabricate profile numbers.
- Very specific: line 170
When a table is driven end-to-end, the retail-orchestrate conductor invokes this wizard as its Source -> Mapping leg (Phases 1-4).
≈ “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
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
retailsubcommand 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) ormapping_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 callsretail-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.mdrows; 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-mappingto 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 observe | Current stage / action |
No mappings/<table>/ dir | Start at Stage 1 (profile). |
source-profile.md present, no source-map.yaml | Resume 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 recorded | Mapping 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(neverIS NULLalone -- 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'spii:flag, gold placement;assumptions.md-- RC1-RC16 adopted/deviated, each deviation citing a data fact;unresolved-questions.md-- the open judgment calls (Gate status: OPENuntil a human clears it);- the
reconciliation-report.mdblank (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) -- withevidence[]orblocking_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:
| Seam | Trigger | Propose (with data fact) | Owner |
| Grain | candidate PK not unique on the rows | report the duplicate count; propose the finer grain / composite PK -- never collapse or pick silently | analyst |
| PII publish-safety | a pii:true candidate column | propose the default (drop before the BI layer, RC4); raise the publish-safety question | governance |
| Business rollup / segment | a categorical needing a value->group mapping | NEVER invent the mapping; raise it for the analyst-supplied table; default unmapped -> UNMAPPED | analyst |
| Product identity | which column authoritatively identifies the entity (or two columns disagree) | report the conflict; never assert identity | analyst / 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-mappingskill. - The downstream build verb (out of scope here): the
retail-build-warehouseskill. - 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.
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.

