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>

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.

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.

<evidence_gathering>

Source Priority

• Direct observation — read code, run searches, examine files

• Documentation — official docs, inline comments, ADRs

• Tests — reveal intended behavior and edge cases

• History — git log, commit messages, PR discussions

• External research — library docs, Stack Overflow, RFCs

• Inference — logical deduction from available evidence

• 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 }

• {FINDING} — evidence: {SOURCE}

• {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>

Loop: Gather → Analyze → Update Confidence → Next step

• Calibrate starting confidence — what do we already know?

• Identify evidence sources — where can we look?

• Gather systematically — collect from multiple angles

• Cross-reference findings — verify patterns hold

• Flag uncertainties — mark gaps with △

• Synthesize conclusions — connect evidence to insights

• 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

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?

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

Core methodology:

• confidence.md — confidence calibration (shared with pathfinding)

• 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)