codebase-analysis

# Codebase Analysis Evidence-based investigation → findings → confidence-tracked conclusions. ## Steps 1. Gather evidence from multiple sources (code, docs, tests, history) 2. Track confidence level as investigation progresses 3. Based on findings: - If pattern analysis needed → load the `find-patterns` skill - If root cause investigation → load the `find-root-causes` skill - If ready to report → load the `report-findings` skill 4. Deliver findings with confidence level and caveats <when_to_use> - Codebase exploration and understanding - Architecture analysis and mapping - Pattern extraction and recognition - Technical research within code - Performance or security analysis NOT for: wild guessing, assumptions without evidence, conclusions before investigation </when_to_use> <confidence> | Bar | Lvl | Name | Action | | ------- | --- | ------------- | --------------------------------- | | `░░░░░` | 0 | Gathering | Collect initial evidence | | `▓░░░░` | 1 | Surveying | Broad scan, surface patterns | | `▓▓░░░` | 2 | Investigating | Deep dive, verify patterns | | `▓▓▓░░` | 3 | Analyzing | Cross-reference, fill gaps | | `▓▓▓▓░` | 4 | Synthesizing | Connect findings, high confidence | | `▓▓▓▓▓` | 5 | Concluded | Deliver findings | _Calibration: 0=0–19%, 1=20–39%, 2=40–59%, 3=60–74%, 4=75–89%, 5=90–100%_ Start honest. Clear codebase + focused question → level 2–3. Vague or complex → level 0–1. At level 4: "High confidence in findings. One more angle would reach full certainty. Continue or deliver now?" Below level 5: include `△ Caveats` section. </confidence> <principles> ## Core Methodology **Evidence over assumption** — investigate when you can, guess only when you must. **Multi-source gathering** — code, docs, tests, history, web research, runtime behavior. **Multiple angles** — examine from different perspectives before concluding. **Document gaps** — flag uncertainty with △, track what's unknown. **Show your work** — findings include supporting evidence, not just conclusions. **Calibrate confidence** — distinguish fact from inference from assumption. </principles> <evidence_gathering> ## Source Priority 1. **Direct observation** — read code, run searches, examine files 2. **Documentation** — official docs, inline comments, ADRs 3. **Tests** — reveal intended behavior and edge cases 4. **History** — git log, commit messages, PR discussions 5. **External research** — library docs, Stack Overflow, RFCs 6. **Inference** — logical deduction from available evidence 7. **Assumption** — clearly flagged when other sources unavailable ## Investigation Patterns **Start broad, then narrow:** - File tree → identify relevant areas - Search patterns → locate specific code - Code structure → understand without full content - Read targeted files → examine implementation - Cross-reference → verify understanding **Layer evidence:** - What does the code do? (direct observation) - Why was it written this way? (history, comments) - How does it fit the system? (architecture, dependencies) - What are the edge cases? (tests, error handling) **Follow the trail:** - Function calls → trace execution paths - Imports/exports → map dependencies - Test files → understand usage patterns - Error messages → reveal assumptions - Comments → capture historical context </evidence_gathering> <output_format> ## During Investigation After each evidence-gathering step emit: - **Confidence:** {BAR} {NAME} - **Found:** { key discoveries } - **Patterns:** { emerging themes } - **Gaps:** { what's still unclear } - **Next:** { investigation direction } ## At Delivery (Level 5) ### Findings { numbered list of discoveries with supporting evidence } 1. {FINDING} — evidence: {SOURCE} 2. {FINDING} — evidence: {SOURCE} ### Patterns { recurring themes or structures identified } ### Implications { what findings mean for the question at hand } ### Confidence Assessment Overall: {BAR} {PERCENTAGE}% High confidence areas: - {AREA} — {REASON} Lower confidence areas: - {AREA} — {REASON} ### Supporting Evidence - Code: { file paths and line ranges } - Docs: { references } - Tests: { relevant test files } - History: { commit SHAs if relevant } - External: { URLs if applicable } ## Below Level 5 ### △ Caveats **Assumptions:** - {ASSUMPTION} — { why necessary, impact if wrong } **Gaps:** - {GAP} — { what's missing, how to fill } **Unknowns:** - {UNKNOWN} — { noted for future investigation } </output_format> <specialized_techniques> Load skills for specialized analysis (see Steps section): - **Pattern analysis** → `find-patterns` - **Root cause investigation** → `find-root-causes` - **Research synthesis** → `report-findings` - **Architecture analysis** → see [architecture-analysis.md](references/architecture-analysis.md) </specialized_techniques> <workflow> Loop: Gather → Analyze → Update Confidence → Next step 1. **Calibrate starting confidence** — what do we already know? 2. **Identify evidence sources** — where can we look? 3. **Gather systematically** — collect from multiple angles 4. **Cross-reference findings** — verify patterns hold 5. **Flag uncertainties** — mark gaps with △ 6. **Synthesize conclusions** — connect evidence to insights 7. **Deliver with confidence level** — clear about certainty At each step: - Document what you found (evidence) - Note what it means (interpretation) - Track what's still unclear (gaps) - Update confidence bar </workflow> <validation> Before concluding (level 4+): **Check evidence quality:** - ✓ Multiple sources confirm pattern? - ✓ Direct observation vs inference clearly marked? - ✓ Assumptions explicitly flagged? - ✓ Counter-examples considered? **Check completeness:** - ✓ Original question fully addressed? - ✓ Edge cases explored? - ✓ Alternative explanations ruled out? - ✓ Known unknowns documented? **Check deliverable:** - ✓ Findings supported by evidence? - ✓ Confidence calibrated honestly? - ✓ Caveats section included if <100%? - ✓ Next steps clear if incomplete? </validation> <rules> ALWAYS: - Investigate before concluding - Cite evidence sources with file paths/URLs - Use confidence bars to track certainty - Flag assumptions and gaps with △ - Cross-reference from multiple angles - Document investigation trail - Distinguish fact from inference - Include caveats below level 5 NEVER: - Guess when you can investigate - State assumptions as facts - Conclude from single source - Hide uncertainty or gaps - Skip validation checks - Deliver without confidence assessment - Conflate evidence with interpretation </rules> <references> Core methodology: - [confidence.md](${CLAUDE_PLUGIN_ROOT}/skills/pathfinding/references/confidence.md) — confidence calibration (shared with pathfinding) Micro-skills (load as needed): - `find-patterns` — extracting and validating patterns - `find-root-causes` — systematic problem diagnosis - `report-findings` — multi-source research synthesis Local references: - [architecture-analysis.md](references/architecture-analysis.md) — system structure mapping Related skills: - `pathfinding` — clarifying requirements before analysis - `debugging` — structured bug investigation </references>