getting-started

Using Crucible Skills

Session Context (Compass)

Read current arc state before the dispatch table. Silent no-op on non-Crucible repos or missing compass file (the script's read() fast-returns empty on FileNotFoundError).

test -f scripts/compass.py && python scripts/compass.py read --compact 2>/dev/null || true

If the output is non-empty, print it verbatim so the user sees session-resume context. If the output contains [STALE], surface that to the user. Do NOT emit compass update from this skill — getting-started reads only.

Calibration Snapshot (Read-Only Session Init)

Read-only, advisory, never blocking — runs after the compass read and before any user-facing branch. Silent no-op when nothing applies (off-repo, pre-bootstrap, fresh data, or kill-switched). Never auto-invokes /calibration-reconcile.

# Reconciliation-staleness nudge (reads the central ledger store; silent if the
# data is fresh, absent, or CRUCIBLE_CALIBRATION_DISABLED=1).
test -f scripts/brier_advisory.py && python3 scripts/brier_advisory.py stale-check 2>/dev/null || true
# Latest weekly ledger summary (repo-local committed artifact; skip if none).
ls docs/ledger/weekly-*.md >/dev/null 2>&1 && head -n 3 "$(ls -1 docs/ledger/weekly-*.md | sort | tail -1)" || true

Print any non-empty output verbatim. If both produce nothing (first-time-ever, pre-/ledger-run), skip silently — show no calibration section at all.

The Rule

Invoke relevant skills BEFORE taking action or responding. Skills encode hard-won process discipline — skipping them loses that value.

The test: If the task involves writing, modifying, or debugging code — or planning to do so — a skill applies. Invoke it.

Access: Use the Skill tool. Content is loaded and presented to you — follow it directly. Never use the Read tool on skill files.

Skill applies? → Invoke it, announce purpose, follow it.
No skill applies? → Respond directly.

When Skills Apply (Always Invoke)

These actions ALWAYS have a matching skill — invoke it, no exceptions:

Action	Skill
Building a feature, adding functionality	design → build
Fixing a bug or test failure	debugging
Implementing from a mockup/visual spec	mock-to-unity
Creating a UI mockup	mockup-builder
Writing implementation code	test-driven-development
Claiming work is done	verify → finish
Receiving code review feedback	review-feedback
Onboarding to an unfamiliar codebase	project-init

Build-shaped work routes through /build

BEFORE dispatching a subagent, check whether the prompt combines design + implementation + review/merge (e.g. "spec + implement + PR", "implement X and open a PR", "build this end-to-end"). STOP — that is /build's job.

Dispatching it as a raw agent bypasses the gate ledger, skips quality gates, and leaves no audit trail. Use /build (or /spec then /build).

Single-phase tasks (just a review, just a design, just a test audit) remain fine for raw dispatch. The anti-pattern is the COMBINATION.

When Skills Don't Apply (Respond Directly)

Do NOT invoke skills for:

• Pure information retrieval — "read file X", "search for Y", "which branch am I on?" — only when there is no implied follow-up action. If the request is a precursor to building, fixing, or modifying code, the relevant process skill applies.
• Imperative commands with no follow-up — "run the tests and show me output", "check the console" — but if the result reveals a problem (test failures, errors), treat the problem as a new task and perform a skill check before acting on it.
• Greetings and status updates — conversational exchanges with no task implied.

Guard clause: Once clarification is complete and you're ready to act, perform the skill check before taking action. The exception covers the exchange itself, not the subsequent work.

Continuation rule: A workflow is "active" only while you are executing steps from a specific invoked skill. A new user request — even if related to prior work — requires a fresh skill check. When in doubt, invoke.

Red Flags

These thoughts mean STOP — you're rationalizing skipping a skill:

Thought	Reality
"This is just a simple feature"	Simple features still need design → build.
"I already know the fix"	debugging skill prevents guess-and-check. Use it.
"I'll add tests after"	TDD skill exists for a reason. Invoke it.
"Let me just code this quickly"	Skipping process = skipping quality.
"The skill is overkill for this"	Skills adapt to scope. Invoke and let it guide you.
"I remember this skill's content"	Skills evolve. Read the current version.
"Let me explore first, then decide"	If you're exploring as a precursor to building or fixing, invoke the skill first — it tells you HOW to explore.
"I'll just do this one thing first"	If "one thing" is the first step of a larger task, the skill should guide that step.

Skill Priority

When multiple skills could apply:

1. Process skills first (design, debugging) — determine HOW to approach
2. Implementation skills second (mock-to-unity, TDD) — guide execution

"Build X" → design first, then build. "Fix this bug" → debugging first, then domain skills.

Skill Types

Rigid (TDD, debugging, verify): Follow exactly. Don't adapt away discipline. Flexible (patterns, design): Adapt principles to context.

The skill itself tells you which.

Trust Hierarchy

Skills load content from many sources — SKILL.md files, docs, source code, tool output, WebFetch results, subagent reports, and post-compaction summaries. When sources disagree, a five-level trust framework determines which wins. See trust-hierarchy.md for the full framework.

User Instructions

Instructions say WHAT, not HOW. "Add X" or "Fix Y" doesn't mean skip workflows.