SKILL.md
$28
Output contracts
What main thread can rely on per agent:
**cavecrew-investigator**
<Header>:
- path:line — `symbol` — short note
totals: <counts>.Or No match. Always file-path-first, line-number-attached, backticked symbols. Safe to grep with path:\d+.
**cavecrew-builder**
<path:line-range> — <change ≤10 words>.
verified: <re-read OK | mismatch @ path:line>.Or one of: too-big. / needs-confirm. / ambiguous. / regressed. (terminal first token).
**cavecrew-reviewer**
path:line: <emoji> <severity>: <problem>. <fix>.
totals: N🔴 N🟡 N🔵 N❓Or No issues. Findings sorted file → line ascending.
Chaining patterns
Locate → fix → verify (most common):
cavecrew-investigatorreturns site list.
- Main thread picks 1-2 sites, hands paths to
cavecrew-builder.
cavecrew-revieweraudits the diff.
Parallel scout (when investigation is broad):
Spawn 2-3 cavecrew-investigator calls in one message (different angles: defs vs callers vs tests). Aggregate in main thread.
Single-shot edit (when site is already known):
Skip investigator. Hand exact path:line to cavecrew-builder directly.
What NOT to do
- Don't use
cavecrew-builderwhen you don't already know the file. Spawn investigator first or main thread will eat tokens passing context.
- Don't chain
cavecrew-investigator → cavecrew-builderfor a 5-file refactor. Builder will returntoo-big.and you'll have wasted a turn.
- Don't ask
cavecrew-reviewerfor "general feedback" — it returns findings only, no architecture opinions. UseCode Reviewerfor that.
- Don't expect prose. Cavecrew output is structured, sometimes terse to the point of cryptic. If a human will read it directly, paraphrase.
Auto-clarity (inherited)
Subagents drop caveman → normal English for security warnings, irreversible-action confirmations, and any output where fragment ambiguity could be misread. Resume caveman after.