re_struct/rules/discovery-waves.md

Hierarchical Wave Analysis

Large codebases must be analyzed in waves — never attempt full analysis in a single session. Each wave produces a condensed document that replaces raw context for subsequent waves.

Wave 1 — Structure, No Code

• Read only directory structure and file names (ls, tree, glob) — do NOT open files
• Derive: rough modules, layers, top-level organization
• Output: docs/A_discovery/structure-map.md
• Context cost: minimal

Wave 2 — Entry Points and Dependencies

• Read only structurally informative files: project files (.csproj, package.json, pom.xml), main routers/controllers, DB migrations/schema files, configuration
• Do NOT read business logic yet
• Output: docs/A_discovery/entry-points.md
• Context loaded: structure-map.md

Wave 3 — Module-by-Module Deep Dive

• One module = one session (or one subagent)
• Analyze ONLY the subtree for that module — ignore everything else
• Context loaded: structure-map.md + capabilities-inventory.md (current state)
• Output per module: dedicated discovery document in docs/A_discovery/
• After each module: update capabilities-inventory.md with new findings

Key Principles

• Each wave produces a condensed document that replaces raw context
• Raw code (large, unstructured) → condensed docs (small, oriented) → growing inventory
• Never load the full codebase into a single session
• When dispatching parallel agents for Wave 3: each agent gets exactly one module subtree
• Track analyzed modules explicitly in task.md with checkboxes

Wave Progression

Raw code (large, unstructured)
    ↓ Wave 1
structure-map.md (small, orienting)
    ↓ Wave 2
entry-points.md (small, precise)
    ↓ Wave 3 × N modules
domain-model.md, capabilities-inventory.md (growing, condensed)