deep-analysis

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

1. 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.
2. 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.
3. 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.
4. Refuted findings are discarded from the roadmap but kept (struck through) in the area docs — so future audits don't re-litigate them.
5. 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.
6. No silent caps. If anything was sampled, truncated, or skipped, the report says so.
7. 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.