agentleFS
KemetraKemetra/Seshat-BI/.claude/skills/first-hour-compass/SKILL.md

first-hour-compass

Skill2 starsChanged 4 months agoApache-2.0View on GitHub

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.

The file

We split this skill into the rules it gives an agent

2 rules. About 0 are common, 1 is distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Emits no score: No numeric health / confidence / percent-ready / maturity value.

    line 37
  2. Very specific:

    When there is no table yet -- the user has just arrived and named nothing -- do not stop at "run retail-onboard-table".

    line 62

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

Keep what fits and drop the rest. Your version, ready for your agents.
Files
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 fieldSource (copied verbatim)
You are herereadiness-status.yaml current_stage + that stage's status
Next stagethe FIRST non-pass stage in pipeline order (Source -> Mapping -> Silver -> Gold -> Semantic Model -> Dashboard -> Publish)
Next artifactthe required artifact named in that stage's readiness definition
Authoring skillthe cross-walk row for that stage in the compass card template
STOP rowsthat stage's blocking_reasons[] verbatim + an approval-required flag
Conflict flagssurfaced (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 exampleWhat it demonstratesPick it when your table is...
retail-store-salesThe 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.