Codebase Recon

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 outfitter:patterns skill
• If root cause investigation → load the outfitter:find-root-causes skill
• If ready to report → load the outfitter: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>

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 → outfitter:patterns
• Root cause investigation → outfitter:find-root-causes
• Research synthesis → outfitter:report-findings
• Architecture analysis → see 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 — confidence calibration (shared with pathfinding)

Micro-skills (load as needed):

• outfitter:patterns — extracting and validating patterns
• outfitter:find-root-causes — systematic problem diagnosis
• outfitter:report-findings — multi-source research synthesis

Local references:

• architecture-analysis.md — system structure mapping

Related skills:

• outfitter:pathfinding — clarifying requirements before analysis
• outfitter:debugging — structured bug investigation

</references>

Architecture Analysis

Techniques for analyzing system structure, dependencies, and component relationships.

Dependency Mapping

Forward Dependencies

What a component relies on: 1. Direct imports — explicit dependencies in code 2. Indirect references — called through interfaces 3. Runtime dependencies — configuration, environment 4. Data dependencies — shared state, databases

Reverse Dependencies

What relies on this component: 1. Direct dependents — explicit imports from other modules 2. Interface consumers — components using this API 3. Side effect consumers — code relying on mutations 4. Event subscribers — listeners for this component's events

Circular Dependencies

Red flags:

• A imports B, B imports A
• Longer cycles: A → B → C → A
• Implicit cycles through shared state

Resolution strategies:

• Extract shared code to separate module
• Introduce interface/abstraction layer
• Invert dependency direction
• Break into smaller components

Layer Identification

Detecting Layers

Look for:

• Directional flow — data/control flows one way
• Abstraction levels — concrete → abstract as you ascend
• Responsibility clustering — similar concerns grouped
• Interface boundaries — clear contracts between groups

Common Layer Patterns

Three-tier:

• Presentation (UI, API endpoints)
• Business logic (domain, workflows)
• Data access (repositories, queries)

Hexagonal/Clean:

• Core domain (entities, business rules)
• Application layer (use cases, orchestration)
• Infrastructure (frameworks, external services)
• Interfaces (controllers, adapters)

Microservices:

• Service boundary (API gateway)
• Service logic (domain per service)
• Data layer (per-service database)
• Cross-cutting (auth, logging, monitoring)

Layer Violations

Violations indicate architectural drift:

• Lower layer imports higher layer
• Business logic in presentation layer
• Data access code in domain entities
• Infrastructure concerns leaking into core

Interface Analysis

Contract Definition

Examine:

• Input types — what does it accept?
• Output types — what does it return?
• Error modes — what can fail, how?
• Side effects — mutations, I/O, state changes
• Invariants — what must always be true?

API Quality

Strong interfaces show:

• Cohesion — methods belong together
• Minimal surface — small, focused API
• Clear contracts — types tell the story
• Stability — changes don't cascade
• Composability — works well with others

Weak interfaces show:

• Kitchen sink — unrelated methods bundled
• Leaky abstractions — implementation details exposed
• Unstable — frequent breaking changes
• Rigid — hard to extend or compose

Component Relationships

Relationship Types

Composition:

• Component owns sub-components
• Lifecycles coupled
• Strong cohesion
• Example: Page owns Header, Footer

Aggregation:

• Component references others
• Independent lifecycles
• Loose coupling
• Example: ShoppingCart references Product

Dependency:

• Uses another component's interface
• No ownership
• Can be swapped
• Example: AuthService uses Database

Association:

• Knows about but doesn't own
• Weak relationship
• Often bidirectional
• Example: User ↔ Post (many-to-many)

Coupling Analysis

Low coupling (good):

• Communicate through interfaces
• Few shared assumptions
• Changes localized
• Easy to test in isolation

High coupling (risky):

• Direct field access
• Shared mutable state
• Knowledge of implementation
• Changes ripple widely

Architectural Pattern Recognition

Layered Architecture

Indicators:

• Unidirectional dependencies (top → bottom)
• Each layer uses only layer below
• Clear separation of concerns

Trade-offs:

• ✓ Simple, well-understood
• ✓ Easy to enforce rules
• ✗ Can become rigid
• ✗ Performance overhead

Event-Driven Architecture

Indicators:

• Pub/sub or message queues
• Decoupled components
• Asynchronous communication
• Event sourcing patterns

Trade-offs:

• ✓ Scalable, resilient
• ✓ Loose coupling
• ✗ Harder to reason about flow
• ✗ Eventual consistency challenges

Microservices

Indicators:

• Service per bounded context
• Independent deployment
• API-based communication
• Decentralized data

Trade-offs:

• ✓ Independent scaling
• ✓ Technology diversity
• ✗ Distributed system complexity
• ✗ Operational overhead

Analysis Workflow

Top-Down

Start broad, narrow focus: 1. System boundaries — what's in scope? 2. Major components — high-level modules 3. Component interactions — how they communicate 4. Internal structure — zoom into each component 5. Implementation — code-level details

Bottom-Up

Start specific, build understanding: 1. Entry point — main(), server start, UI root 2. Call graph — trace execution paths 3. Cluster calls — group related functionality 4. Extract components — identify logical boundaries 5. Map relationships — connect the pieces

Targeted

Focus on specific concern: 1. Define question — what are you trying to understand? 2. Identify relevant code — where does this happen? 3. Trace dependencies — what does it touch? 4. Analyze impact — what would changing this affect? 5. Document findings — capture insights

Documentation Extraction

From architecture analysis, capture:

• Component diagram — boxes and arrows
• Dependency graph — what imports what
• Layer diagram — abstraction levels
• Sequence diagrams — interaction flows
• Decision records — why this structure?