mwguerra/plugins/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 <subsystem>"
• 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

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.

1. 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.

1. 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.

1. **Refuted findings are discarded from the roadmap but kept (struck through) in the

area docs** — so future audits don't re-litigate them.

1. 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.

1. No silent caps. If anything was sampled, truncated, or skipped, the report says so.
2. 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.