| name | deep-analysis |
| description | Use when asked for a deep audit, production-readiness review, architecture review, or prioritized recommendations across a codebase or subsystem — orchestrates parallel reader agents with adversarial verification and publishes findings to docs/deep-analysis/ |
Deep Analysis Methodology
A multi-agent audit that produces adversarially verified, prioritized,
evidence-anchored findings — not a single-agent essay. Orchestration:
commands/deep-analysis.md. This skill holds the principles that survive
adaptation.
The five phases
| Phase | What | Why it exists |
|---|
| 0 Scout | Inline: manifests, tree, git log, CLAUDE.md | areas need file anchors; git log reveals features newer than docs |
| 1 Select | Areas picked from the library by the lookup table — never authored | pre-written anchored prompts produce evidence (H6 compiled away) |
| 2 Map+Verify | One reader per selected area; one skeptic per critical/high flaw, prompted to REFUTE | recall from narrow readers; precision from refute-default skeptics |
| 3 Synthesize | Roadmap agent ‖ completeness critic | one priority list; the critic catches blind spots in the plan itself |
| 4 Publish | docs/deep-analysis/** + condensed report | findings outlive the conversation |
Non-negotiable principles
- Readers return structured data, not prose. Schema:
summary,
implemented[], gaps[] (missing), flaws[] (existing-but-wrong, each with
evidence citing file:line), questions[]. Gaps and flaws split because they
get different priorities and different fixes.
- Severity is defined, not vibes. critical = money/data loss or security hole;
high = broken common path; medium = edge case or missing safeguard; low = polish.
Give the scale to every agent verbatim.
- Skeptics default to refuted. Read the cited files AND the call chain (guards
may live in callers); check intentional/configurable; confirm only what survives
your own reading. Skeptics may correct severity in either direction.
- Refuted findings are discarded from the roadmap but kept (struck through) in
the area docs — future audits don't re-litigate them.
- Flow mapping beats feature listing where the lookup table selects a flow
area: one row per flow, trigger → calls → callbacks → state transitions →
events → verdict (
complete/partial/missing/flawed).
- No silent caps. Anything sampled, truncated, or skipped is stated.
- The roadmap is bucketed by when-to-fix (P0/P1/P2/quick wins), each item with
a one-line why and effort S/M/L/XL.
Model pins (ADR-0001)
- Planner (area selection beyond the lookup table + roadmap synthesis):
model: sonnet — clustering N findings into root causes is synthesis, not
checking. Pinned per docs/adr/0001-haiku-default-with-pinned-judgment-cores.md.
- Readers and skeptics:
model: haiku (the default executor).
Sizing (countable, no discretion)
| Repo size (LOC) | Areas |
|---|
| < 20k | 6–8 |
| 20–100k | 10–14 |
| > 100k | 14–16 (hard cap) |
Skeptic count = confirmed critical/high flaw count (one skeptic per flaw). A
focused ask ("audit just the webhook layer") keeps the same shape at 3–5 areas.
Phase 2 (verification) is never skipped.
References (load ONE, by situation)
Companion processes
- The roadmap feeds
implementation: known flaws get fixed first, built around,
or surfaced — never silently built upon.
- An audit spanning multiple sessions runs as a deep-work run (
runs +
run_steps — docs/architecture/runtime-state.md); the board lives in the
store, not in a thoughts/ directory.
