deep-code-scan

name

deep-code-scan

description

Multi-lane, decomposition-first codebase scan campaign that writes markdown docs only. Use when the user asks for a deep code scan, comprehensive audit, whole-repo issue hunt, or organized remediation plan spanning multiple lanes such as correctness, tests, performance, security, quality, structure, or architecture without adopting agile-workflow. Interviews for goal, lanes, rigor, scanner tier, and altitude bands; maps the repo; fans out scoped scanners; runs a review gauntlet; and consolidates findings into a code-audit scan folder of markdown documents.

Deep Code Scan

Orchestrate a goal-driven scan campaign: decompose the codebase, scan from narrow components outward, verify findings, and produce an organized remediation plan. This standalone variant writes markdown documents under code-audit/scan-<goal>/. It never creates .work/ items, backlog entries, release gates, or commits.

Use this when the scan spans multiple lanes or needs the decompose -> scan -> review -> consolidate campaign shape. For a single-domain pass, route to the specialist skill: bug-scan, perf-scout, repo-eval, or bold-refactor.

Deliverables

Default output root:

code-audit/scan-<goal>/
  00-plan.md
  01-component-map.md
  02-findings-ledger.md
  03-review-gauntlet.md
  04-remediation-plan.md

Temporary scanner packets may live under code-audit/scan-<goal>/.artifacts/ while the campaign is running. After final collation, remove that scratch directory unless the user asks to keep raw packets.

Composition, Not Replacement

In-campaign scanners reuse local reference catalogs. Do not invoke specialist skills mid-campaign; load their references as scanner knowledge:

Lane	Reference source	Standalone alternative
correctness	../bug-scan/references/*	bug-scan <path>
performance	../perf-scout/references/*	perf-scout <path>
quality / holistic	../repo-eval/references/*	repo-eval <path>
architecture / bold	../bold-refactor/SKILL.md conceptual lenses	bold-refactor <path>
tests	lane-catalog test guidance	focused test-audit scanner
tests	lane-catalog test guidance	test-scan <path>
security	lane-catalog security guidance	security-scan <path>
structure / refactor	lane-catalog refactor guidance plus project pattern docs	focused structure scanner
custom	bespoke brief from the user's goal	none

Dials

Set these with the user before scanning:

• Goal: the north star, such as all-issues, correctness, performance, or a custom phrase.
• Lanes: selected scan domains. all-issues selects correctness, tests, performance, security, quality, and structure. Architecture/bold is opt-in.
• Rigor: floor, standard, or full.
• Scanner tier: mixed, codex-high, codex-xhigh, claude-opus, claude-sonnet, or the nearest host-native equivalents.
• Altitude bands: default leaf -> module -> subsystem -> system; trim for small repos.

Compute an agent budget before scanning. If the plan implies more than about 150 total scanner/review calls or more than 20 scanners in one wave, surface that cost and narrow the plan unless the user explicitly accepts it.

Phase 1: Kickoff Interview

Read enough of the repo to propose grounded dials: top-level layout, manifests, languages, entry points, tests, and docs. Ask concise questions or use a structured question tool to settle the dials.

Do not proceed to fan-out until the user has approved the goal, lanes, bands, and budget.

Phase 2: Decompose The Codebase

Build the altitude component map. Read references/decomposition.md for the method.

Output the approved map to 01-component-map.md: band -> components, where each component has a stable slug, role, file set, and parent edges for roll-up.

Phase 3: Write The Plan

Create 00-plan.md before scanning. It records:

• goal and scope;
• selected lanes and why;
• altitude bands and component counts;
• scanner tier per lane;
• rigor;
• estimated scanner calls and review calls;
• output root and temporary artifact policy.

Stop and present the plan. Adjust if the user redirects.

Phase 4: Drive The Scan

Walk each lane and its bands from narrow to broad. At each band, fan out parallel scanner sub-agents across components. Read references/scanner-brief.md for the dispatch brief and finding schema.

Each scanner is read-only over source code and writes only its assigned temporary markdown packet. The orchestrator spot-checks candidate findings, writes accepted findings to 02-findings-ledger.md, and rolls concise inherited findings upward to the next band.

Phase 5: Review Gauntlet

Run the review gauntlet before consolidation. Read references/review-gauntlet.md. At standard rigor, run at least two fresh-context review rounds; at full, run to convergence or cap at four rounds. Record the ledger in 03-review-gauntlet.md.

Phase 6: Consolidate

Cluster surviving findings into an implementation-neutral remediation plan. Read references/consolidation.md. Write 04-remediation-plan.md with:

• findings grouped by fix locality and theme;
• severity and confidence;
• recommended sequence;
• risks and intent constraints;
• validation checks to run before and after implementation;
• advisory findings that did not become recommended work.

Ask before writing the final remediation plan if the campaign is large enough that the clusters are a substantial commitment.

Phase 7: Close

Make sure the five markdown deliverables are present and internally consistent. Remove code-audit/scan-<goal>/.artifacts/ after final collation unless the user asked to keep it. Summarize to the user:

• output root;
• lanes and components scanned;
• severity counts;
• top clusters;
• review-gauntlet outcome;
• recommended next implementation step.

Guardrails

• Plan before scanning.
• Load specialist references as knowledge; do not invoke specialist skills mid-campaign.
• Findings need file:line and in-context rationale.
• Review findings before turning them into recommendations.
• Consolidate; do not flood the report with one disconnected task per finding.
• Do not implement fixes.
• Do not write .work/, backlog, release, or tracking artifacts.