Exhaustive Systems Analysis

Systematic audit methodology for rooting out latent issues in codebases, particularly agent-written code that needs verification before production use.

Core Principles

1. Subsystem isolation — Analyze each subsystem separately to prevent context pollution
2. Evidence-based findings — Every issue must cite specific code locations
3. Severity-driven prioritization — Critical issues first, cosmetic issues last
4. Assume all issues will be fixed — Don't hedge; be direct about what's wrong

Workflow

Phase 1: System Decomposition

Before analysis, map the system's subsystems. Auto-discover by:

1. Read project structure — Identify major modules, packages, or directories
2. Trace data flow — Follow how data enters, transforms, and exits
3. Identify side effects — File I/O, network, database, IPC, state mutations
4. Map dependencies — Which subsystems depend on which

Output a subsystem table:

| # | Subsystem | Files | Side Effects | Priority |
|---|-----------|-------|--------------|----------|
| 1 | Lock System | lock.rs | FS: mkdir, rm | High |
| 2 | API Layer | api/*.rs | Network, DB | High |
| 3 | Config Parser | config.rs | FS: read | Medium |

Priority heuristics:

• High: Side effects, state management, security, concurrency
• Medium: Business logic, data transformation, validation
• Low: Pure utilities, formatting, logging

Phase 2: Sequential Analysis

Analyze subsystems in priority order. For large codebases (>5 subsystems or >3000 LOC per subsystem), prefer clearing context between subsystems to prevent analysis drift.

For each subsystem, apply the appropriate checklist based on subsystem type.

Phase 3: Consolidation

After all subsystems analyzed:

1. Deduplicate cross-cutting findings
2. Rank all issues by severity
3. Produce final report with recommended action order

Analysis Checklists

Select checklist based on subsystem characteristics. Apply multiple if applicable.

Stateful Systems (files, databases, caches, locks)

APIs & Network (HTTP, gRPC, WebSocket, IPC)

Concurrency (threads, async, channels, locks)

UI & Presentation (views, components, templates)

Data Processing (parsers, transformers, validators)

Configuration & Setup (config files, environment, initialization)

Severity Classification

Classify every finding. Assume user will fix all issues soon.

Finding Format

Every finding must follow this structure:

### [SUBSYSTEM] Finding N: Brief Title

**Severity:** Critical | High | Medium | Low
**Type:** Bug | Race condition | Security | Stale docs | Dead code | Design flaw
**Location:** `file.rs:line_range` or `file.rs:function_name`

**Problem:**
What's wrong and why it matters. Be specific.

**Evidence:**
Code snippet or reasoning demonstrating the issue.

**Recommendation:**
Specific fix. Include code if helpful.

Output Structure

Adapt output to project organization. Common patterns:

Pattern A: Audit Directory (recommended for 5+ subsystems)

.claude/docs/audit/
├── 00-analysis-plan.md      # Subsystem table, priorities, methodology
├── 01-subsystem-name.md     # Individual analysis
├── 02-another-subsystem.md
└── SUMMARY.md               # Consolidated findings, action items

Pattern B: Single Document (for smaller systems)

.claude/docs/audit/system-name-audit.md
# Contains: plan, all findings, summary

Pattern C: Inline with Existing Docs

If project has existing docs/ or similar, place audit artifacts there.

Always create a summary with:

• Total findings by severity
• Top 5 most critical issues
• Recommended fix order

Session Management

For thorough analysis:

• Small systems (<1000 LOC, <3 subsystems): Single session acceptable
• Medium systems (1000-5000 LOC, 3-7 subsystems): Clear context between phases
• Large systems (>5000 LOC, >7 subsystems): Separate sessions per subsystem

When clearing context, document progress in the analysis plan file so the next session can continue.

Pre-Analysis: Known Issues Sweep

Before deep analysis, scan for documented issues:

1. Check CLAUDE.md / README for "gotchas" or "known issues"
2. Search for TODO/FIXME/HACK comments
3. Review recent commits for bug fixes (may indicate fragile areas)
4. Check issue tracker if accessible

Add these as starting hypotheses—verify or refute during analysis.

Anti-Patterns to Avoid

Completion Criteria

Analysis is complete when:

1. ✅ All high-priority subsystems analyzed
2. ✅ Every finding has severity, location, and recommendation
3. ✅ Summary document exists with prioritized action items
4. ✅ No "TBD" or "needs investigation" items remain
5. ✅ Cross-references between related findings added