getting-started

# Using Crucible Skills

## Session Context (Compass)

<!-- CANONICAL: shared/compass-protocol.md -->

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

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

```bash
# 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](./trust-hierarchy.md) for the full framework.

## User Instructions

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