name	codebase-analysis
version	1.0.0
description	Evidence-based codebase investigation methodology. Use when analyzing codebases, understanding architecture, exploring patterns, or investigating technical problems. Triggers when user asks to analyze, investigate, understand, research, or explore code. Core foundation for analyst and debugger agents.

Codebase Analysis

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

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

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.

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

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 }

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.

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)

codebase-analysis

Install Skill

SKILL.md