| name | deep-analysis |
| description | Use when asked for a deep audit, deep analysis, production-readiness review, architecture assessment, or prioritized recommendations across a whole codebase or subsystem — orchestrates parallel reader agents with adversarial verification and publishes findings to docs/deep-analysis/ |
Deep Analysis Methodology
A multi-agent audit process that produces adversarially verified, prioritized,
evidence-anchored findings — not a single-agent essay.
When this applies
- "Audit this project / is this production ready?"
- "Deeply understand the code and give me prioritized recommendations"
- "Find what's implemented, missing, or flawed in "
- Any request whose honest answer requires reading more code than one context can
carefully hold.
For the full step-by-step orchestration, follow the /deep-analysis command in this
plugin (commands/deep-analysis.md). This skill summarizes the principles so the
process survives 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 Map | 8–15 parallel reader agents, structured schema | Recall: each reader is exhaustive within a narrow area |
| 2 Verify | One skeptic per critical/high flaw, prompted to REFUTE | Precision: readers over-flag; skeptics kill plausible-but-wrong claims |
| 3 Synthesize | Roadmap agent (dedupe, prioritize) ‖ completeness critic | One coherent priority list; critic catches blind spots in the plan itself |
| 4 Publish | docs/deep-analysis/** + condensed conversation report | Findings outlive the conversation; next audit builds on this one |
Non-negotiable principles
- Readers return structured data, not prose. Schema:
summary, implemented[],
gaps[] (missing functionality), flaws[] (existing-but-wrong, each with
evidence citing file:line), questions[] (owner decisions). Separating gaps
from flaws matters: 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. The verify prompt instructs: read the cited files
AND the call chain (guards may live in callers), check if behavior is intentional or
configurable, and only confirm what survives your own reading. Skeptics may also
correct severity in either direction. This is the same refute-by-default discipline
the
adversarial-verify skill applies to any standalone claim.
- Refuted findings are discarded from the roadmap but kept (struck through) in the
area docs — so future audits don't re-litigate them.
- Flow mapping beats feature listing for domains with end-to-end flows (payments,
orders, auth). One row per flow: trigger → outbound calls → callbacks/webhooks →
state transitions → events emitted → verdict (
complete/partial/missing/flawed).
"User pays but nothing activates" class bugs only show up in flow view.
- No silent caps. If anything was sampled, truncated, or skipped, the report says so.
- The roadmap is bucketed by when-to-fix (P0 before production / P1 soon / P2
polish / quick wins < 1h), each item with a one-line why and effort S/M/L/XL.
References
references/workflow-template.js — the Workflow script template (pipeline shape,
schemas, skeptic prompt). Adapt CTX + AREAS; keep the rest.references/output-structure.md — the docs/deep-analysis/ publishing contract.
Scaling guidance
- Reader count = area count; skeptic count = confirmed-candidate count (expect 2–6×
the reader count on a codebase with real issues). A mid-size repo audit lands around
60–90 agents total. This is the intended cost of a trustworthy answer.
- Small/focused asks ("audit just the webhook layer"): same shape, 3–5 areas, same
verification discipline. Never skip Phase 2 to save time.
Companion processes
- The roadmap this produces is the input to the
implementation process: known flaws
get fixed first, built around, or surfaced — never silently built upon.
- For a large multi-place execution that is not itself an audit,
deep-work runs the
plan → adversarial review → serial execute → synthesize loop.
- If an audit is too large for one context window (the synthesizer's board must survive it),
persist that board under
thoughts/<task-slug>/ per the thoughts skill, then drain the settled
findings into docs/deep-analysis/ as usual.
