AGENT SKILL

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
所属仓库
Kemetra/Seshat-BI
最近更新
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 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 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 (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:

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-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.

04 同仓库更多 Skills

Kemetra
Kemetra/Seshat-BI

fake-skill

A fixture skill with declaring frontmatter, used as positive shipped evidence.

★ 2
Kemetra
Kemetra/Seshat-BI

fake-skill

A fixture skill with declaring frontmatter, used as positive shipped evidence.

★ 2
Kemetra
Kemetra/Seshat-BI

bare-skill-no-frontmatter

暂无简介

★ 2
Kemetra
Kemetra/Seshat-BI

fake-skill

A fixture skill with declaring frontmatter, used as positive shipped evidence.

★ 2
Kemetra
Kemetra/Seshat-BI

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.

★ 2
Kemetra
Kemetra/Seshat-BI

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.

★ 2