AGENT SKILL

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
所属仓库
Kemetra/Seshat-BI
最近更新
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 status clean -- 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.md names a required owner and whether an approvals[] 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.yaml only.
  • 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 pass is 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.md itself 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 from templates/, seeded by retail-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 status clean; retail-onboard-table is 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-sales worked example (a narrative pattern, not a template)
  • The onboarding walk this routes into: the retail-onboard-table skill.
  • Usage + boundary: the first-hour-compass usage note.
  • Multi-table parent (F026): the readiness-viewer skill.
  • Static parent (F006): the onboarding checklist.
  • Pipeline ordering + gates: the readiness-pipeline definition.

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