Codebase Analysis

Evidence-based investigation → findings → confidence-tracked conclusions.

<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 micro-skills for specialized analysis:

• Pattern analysis → load pattern-analysis skill
• Root cause investigation → load root-cause-analysis skill
• Research synthesis → load report-findings skill
• Architecture analysis → see architecture-analysis.md

These provide deep-dive methodologies for specific analysis types. </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](../pathfinding/references/confidence.md) — confidence calibration (shared with pathfinding) - [FORMATTING.md](../../shared/rules/FORMATTING.md) — formatting conventions

Micro-skills (load as needed):

• pattern-analysis — extracting and validating patterns
• root-cause-analysis — systematic problem diagnosis
• report-findings — multi-source research synthesis

Local references:

• architecture-analysis.md — system structure mapping

Related skills:

• pathfinding — clarifying requirements before analysis
• debugging-and-diagnosis — structured bug investigation (loads root-cause-analysis) </references>