retail-onboard-table
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).
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-11
- Stars
- ★ 2
- Forks
- 0
01 前言 Front Matter
- name
- retail-onboard-table
- description
- 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).
03 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
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.
04 同仓库更多 Skills
fake-skill
A fixture skill with declaring frontmatter, used as positive shipped evidence.
fake-skill
A fixture skill with declaring frontmatter, used as positive shipped evidence.
bare-skill-no-frontmatter
暂无简介
fake-skill
A fixture skill with declaring frontmatter, used as positive shipped evidence.
retail-kpi-knowledge
Retail KPI / metric-contract reasoning layer for BI agents in the Seshat BI project. Use when an agent must reason about the BUSINESS MEANING of a retail KPI before any implementation — defining a KPI in business terms, classifying additivity (fully/semi/non-additive), identifying grain, listing required source fields, resolving ambiguity (gross vs net, VAT, returns, cost method, same-store), choosing an MVP KPI pack, reviewing a metric contract for completeness, or preparing a clean handoff to an implementation layer. Also use it to classify KPI sufficiency or prepare an owner policy decision packet. This is a meaning/definition + review layer, not an executor: it does not write DAX/SQL/Python, grant readiness, approve policy, or design dashboards. See INDEX.md for live/planned routes; registry.yaml is the authoritative machine-readable inventory.
bi-sql-knowledge
SQL reasoning, validation, reconciliation, transformation, diagnostics, and anti-pattern knowledge layer for Seshat BI agents. Use when a task involves reasoning about source SQL: source profiling, table grain, keys & uniqueness, joins & fan-out amplification, aggregation correctness, COUNT/NULL semantics, deduplication, validation queries, reconciliation queries, silver/gold transformation logic, window/date-time analytics, SQL anti-patterns, or basic SQL performance reasoning, or interpretation of a supplied sanitized PostgreSQL JSON execution plan. The SQL counterpart to bi-dax-knowledge. It is a thinking & validation layer, not a database executor, runtime validator, dbt/Dagster project, or automatic tuning service.