Skill v1.0.0
currentLLM-judged scan90/100version: "1.0.0" name: using-cairn description: Use when working in a repo that has cairn installed — teaches when to invoke cairn, which skills wrap which verification moments, and how YAML specs are derived silently from prose. Routes to spokes for deep topics (YAML authoring, hash placeholders, source-hash comment format, code-reviewer pattern).
What cairn is
Cairn is a verification substrate for AI-coordinated software development. See PLAN.md §"What this is / is not" for the full substrate summary. This skill teaches when to invoke cairn's three wrappers, how YAML specs derive silently from prose, and which spoke to load for specific tasks.
When this skill applies
Three scenarios trigger this skill:
- YAML lifecycle — Is there a
specs/dir with cairn YAML? YAML derives from prose. Read spokeyaml-authoring.md. - Wrap routing — Is the agent executing an implementation plan inside a cairn-tracked claim? Route to the appropriate wrap.
- Code reviewer dispatch — Is a reviewer agent being dispatched against a rubric gate? Read
code-reviewer-pattern.md.
Wrap routing rules
| Situation | Use | |
|---|---|---|
| Executing a plan via subagent dispatch inside a cairn-tracked repo | cairn:subagent-driven-development-with-verdicts | |
Executing a plan outside a cairn-tracked repo (no specs/) | superpowers:subagent-driven-development | |
| Verification before claiming complete, while holding an active cairn claim | cairn:verdict-backed-verification | |
| Verification before claiming complete, no active cairn claim | superpowers:verification-before-completion | |
| Brainstorming, plan writing, test-driven development, receiving code review | superpowers:* originals unchanged. No cairn wrap. |
YAML lifecycle
In a cairn-tracked repo, specs/ YAML is always derived from prose. The human never edits YAML directly. Requirements YAML derives from docs/superpowers/specs/*.md (brainstorming output); task YAML derives from docs/superpowers/plans/*.md (writing-plans output). Derivation is deterministic and byte-identical on re-run. See yaml-authoring.md for the full protocol.
Hash placeholders banner
When binding a verdict, producer_hash and inputs_hash use provisional Ship 3 placeholders.
These hashes are placeholders. They do not reflect toolchain version or input state. Verdicts bound with these values are NOT safe to rely on for cross-run drift detection.
See hash-placeholders.md for the recipe and the future-replacement plan.
Invocation rule
This skill MUST be invoked explicitly by the orchestrating session after each ofsuperpowers:brainstormingandsuperpowers:writing-planscommits. Agent-noticing is unreliable. For harness-enforced belt-and-suspenders drift detection, enable the cairn Stop hook viacairn hook enable. The hook supplements skill discipline; it does not replace it, and it only catches source-hash drift (not skipped verdicts or orphan claims — those are guaranteed by cairn's mutation path itself).
Routing to spokes
| Task you're about to do | Load first | |
|---|---|---|
| Author or regenerate YAML from prose | yaml-authoring.md | |
Compute producer_hash or inputs_hash for a verdict | hash-placeholders.md | |
Read or write the # cairn-derived: comment | source-hash-format.md | |
Dispatch superpowers:code-reviewer against a rubric gate | code-reviewer-pattern.md |
Red flags
| Thought | Reality | |
|---|---|---|
| "I'll just edit the YAML directly" | YAML is derived. Edit the prose; regeneration follows. | |
| "The prose spec is fine, skip the elicitation" | Elicitation checks for cairn-required fields not present in prose. Skipping = malformed YAML downstream. | |
| "Verdict is close enough without evidence" | Core Invariant 3 — no verdict without hash-verified evidence. | |
"Agent said it's done, skip cairn task complete" | Core Invariant 10 — cairn events since must show the completion. |