first-hour-compass
Show a NEW-table author the stateful "you are here / next artifact / authoring skill" orientation card for ONE table in the Seshat BI repo. Use when someone asks "where is this table in the readiness journey", "what do I do next for <table>", or "orient me on a new table". READ-ONLY and invoke-and-present only: it parses that table's mappings/<table>/readiness-status.yaml and RENDERS a single-table orientation card (current stage, the next non-pass stage + the artifact it needs + the authoring skill that produces it, plus recorded STOP rows). It RENDERS recorded state (never recomputes a status, advances a stage, writes a pass, infers/back-fills an approval, or fabricates evidence), runs NO validator, opens NO DB connection, and emits NO numeric health/confidence/percent-ready/maturity score (hard rule #9). It is the STATEFUL single-table sibling of the F026 readiness-viewer (multi-table matrix) and the stateful form of the F006 static onboarding checklist.
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-11
- Stars
- ★ 2
- Forks
- 0
01 前言 Front Matter
- name
- first-hour-compass
- description
- Show a NEW-table author the stateful "you are here / next artifact / authoring skill" orientation card for ONE table in the Seshat BI repo. Use when someone asks "where is this table in the readiness journey", "what do I do next for <table>", or "orient me on a new table". READ-ONLY and invoke-and-present only: it parses that table's mappings/<table>/readiness-status.yaml and RENDERS a single-table orientation card (current stage, the next non-pass stage + the artifact it needs + the authoring skill that produces it, plus recorded STOP rows). It RENDERS recorded state (never recomputes a status, advances a stage, writes a pass, infers/back-fills an approval, or fabricates evidence), runs NO validator, opens NO DB connection, and emits NO numeric health/confidence/percent-ready/maturity score (hard rule #9). It is the STATEFUL single-table sibling of the F026 readiness-viewer (multi-table matrix) and the stateful form of the F006 static onboarding checklist.
03 SKILL.md 正文
First-Hour Compass
The stateful single-table orientation card for a new-table author. F024 module class:
Product Module / read-only. It answers, for ONE table: where am I, what is the next
artifact, which skill authors it, and what human STOP is recorded?
What it does / does NOT do
- Creates no truth. It copies recorded fields; it defines no meaning, sets no status.
- Changes no state. It edits no file and runs no git mutation (a run leaves
git statusclean -- see the read-only proof below). - Infers no approval. It never populates, back-fills, or synthesizes an approval; it only
reports whether the next stage's
<stage>-ready.mdnames a required owner and whether anapprovals[]entry is recorded. - Fabricates no evidence. A missing/absent field is reported as the honest not-started state, never invented.
- Runs no validator, opens no DB. It reads
readiness-status.yamlonly. - Emits no score. No numeric health / confidence / percent-ready / maturity value. A request for one is DECLINED (hard rule #9); orientation is the four explicit statuses + evidence + blockers + the next allowed step.
How it renders (renders, never re-derives)
| Card field | Source (copied verbatim) |
|---|---|
| You are here | readiness-status.yaml current_stage + that stage's status |
| Next stage | the FIRST non-pass stage in pipeline order (Source -> Mapping -> Silver -> Gold -> Semantic Model -> Dashboard -> Publish) |
| Next artifact | the required artifact named in that stage's readiness definition |
| Authoring skill | the cross-walk row for that stage in the compass card template |
| STOP rows | that stage's blocking_reasons[] verbatim + an approval-required flag |
| Conflict flags | surfaced (never auto-corrected): a pass with empty evidence[]; a downstream stage entered while an upstream is not pass |
Honest-state rules
- No file for the table -> "Not yet onboarded -- start at Source Ready with
retail-onboard-table." (Absent is not-started, never a fabricated stage.) - A stage
passis reported only as recorded; the card never sets or upgrades it. - Pipeline ordering is respected: a downstream stage is never presented as reachable while
an upstream gate is not
pass.
First arrival: offer a worked example as the reference pattern
When there is no table yet -- the user has just arrived and named nothing -- do not stop
at "run retail-onboard-table". First give them a concrete pattern to steer by. This is the
first-hour "aha": a new author's fastest path is to hold up a filled example and copy its
shape, not to start from an empty gate.
Present the committed worked example as the reference pattern to steer by:
| Worked example | What it demonstrates | Pick it when your table is... |
|---|---|---|
retail-store-sales |
The full seven-stage spine to Dashboard Ready -- metric contracts, governed model, dashboard design, handoff (on the public Kaggle retail-store-sales dataset) | ...any retail-sales table; it carries the build mechanics AND the later stages (semantic model, dashboard, handoff) |
Then hand off to retail-onboard-table for the user's own table, holding the example
up as the reference for that walk (see the worked-examples index). Be explicit
about what "use this example" means:
- The example is a narrative pattern, not a file template --
retail-store-sales.mditself says "copy this section structure, swap in the new table, run the playbook's 7 phases". So the skill references the example while onboarding; it does not copy files into the user's table dir. (The actual starting artifacts come fromtemplates/, seeded byretail-onboard-table.) - Read-only + route only. This section presents the worked example and routes into the
existing onboarding walk. It creates no truth, seeds no artifact, and writes nothing itself
(the run still leaves
git statusclean;retail-onboard-tableis what later authors files).
Set expectations honestly on the same breath: the agent handles the sequence and the
plumbing; the user still owns the judgment -- grain, PII placement, business rollups, and
metric policy are the four human seams retail-onboard-table will surface and STOP on, never
auto-resolve (Principle V).
The two-condition approval flag
The card flags "approval required" for the next stage only when BOTH hold, read from the stage
doc's "Required owner / approval" field: (1) that stage requires a named human sign-off, and
(2) no matching approvals[] entry is recorded. It never names, infers, or supplies the owner
(mirrors the readiness-viewer contract) -- a Principle-V human seam.
The four judgment seams (surfaced, never resolved -- Principle V)
Grain/uniqueness, PII publish-safety, business rollup/segment, and product identity are human judgment calls. The Compass RE-PRESENTS a recorded STOP touching any of these; it never asserts a grain, clears a PII gap, embeds a rollup/segment, or fixes a product identity.
Deltas vs its parents
- vs F026 readiness-viewer: F026 is the multi-table stage MATRIX (all items, all stages). The Compass is the SINGLE-table, next-artifact, authoring-skill-routed orientation card.
- vs F006 onboarding-checklist: F006 is the STATIC definition-of-done. The Compass is the STATEFUL "you are at Stage N of it" read of the same journey.
Read-only proof
Rendering the card writes nothing. After a run, git status is clean (the skill mutates no
tracked file); the only output is the rendered card in the response.
See also
- The card template + stage->skill cross-walk: the first-hour-compass card template.
- First-arrival reference pattern: the
retail-store-salesworked example (a narrative pattern, not a template) - The onboarding walk this routes into: the
retail-onboard-tableskill. - Usage + boundary: the first-hour-compass usage note.
- Multi-table parent (F026): the
readiness-viewerskill. - Static parent (F006): the onboarding checklist.
- Pipeline ordering + gates: the readiness-pipeline definition.
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.