codebase-analysis

Original source / Raw SKILL.md

---
name: codebase-analysis
version: 1.0.0
description: This skill should be used when analyzing codebases, understanding architecture, or when "analyze", "investigate", "explore code", or "understand architecture" are mentioned.
---

# 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](../pattern-analysis/SKILL.md) skill
- **Root cause investigation** → load [root-cause-analysis](../root-cause-analysis/SKILL.md) skill
- **Research synthesis** → load [report-findings](../report-findings/SKILL.md) skill
- **Architecture analysis** → see [architecture-analysis.md](references/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](../pattern-analysis/SKILL.md) — extracting and validating patterns
- [root-cause-analysis](../root-cause-analysis/SKILL.md) — systematic problem diagnosis
- [report-findings](../report-findings/SKILL.md) — multi-source research synthesis

Local references:
- [architecture-analysis.md](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>


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### ../pattern-analysis/SKILL.md

```markdown
---
name: pattern-analysis
version: 1.0.0
description: This skill should be used when recognizing recurring themes, codifying best practices, extracting reusable workflows, or when "pattern", "recurring", or "repeated" are mentioned.
---

# Pattern Analysis

Identify signals → classify patterns → validate with evidence → document for reuse.

<when_to_use>

- Recognizing recurring themes in work or data
- Codifying best practices from experience
- Extracting workflows from repeated success
- Identifying anti-patterns from repeated failures
- Building decision frameworks from observations

NOT for: single occurrences, unvalidated hunches, premature abstraction

</when_to_use>

<signal_identification>

Watch for these signal categories:

| Category | Watch For | Indicates |
|----------|-----------|-----------|
| **Success** | Completion, positive feedback, repetition, efficiency | Pattern worth codifying |
| **Frustration** | Backtracking, clarification loops, rework, confusion | Anti-pattern to document |
| **Workflow** | Sequence consistency, decision points, quality gates | Process pattern |
| **Orchestration** | Multi-component coordination, state management, routing | Coordination pattern |

See [signal-types.md](references/signal-types.md) for detailed taxonomy.

</signal_identification>

<pattern_classification>

Four primary pattern types:

| Type | Characteristics | Use When |
|------|-----------------|----------|
| **Workflow** | Sequential phases, clear transitions, quality gates | Process has ordered steps |
| **Orchestration** | Coordinates components, manages state, routes work | Multiple actors involved |
| **Heuristic** | Condition → action mapping, context-sensitive | Repeated decisions |
| **Anti-Pattern** | Common mistake, causes rework, has better alternative | Preventing failures |

See [pattern-types.md](references/pattern-types.md) for templates and examples.

</pattern_classification>

<evidence_thresholds>

## Codification Criteria

Don't codify after first occurrence. Require:
- **3+ instances** — minimum repetition to establish pattern
- **Multiple contexts** — works across different scenarios
- **Clear boundaries** — know when to apply vs not apply
- **Measurable benefit** — improves outcome compared to ad-hoc approach

## Quality Indicators

| Strong Pattern | Weak Pattern |
|----------------|--------------|
| Consistent structure | Varies each use |
| Transferable to others | Requires specific expertise |
| Handles edge cases | Breaks on deviation |
| Saves time/effort | Overhead exceeds value |

</evidence_thresholds>

<progressive_formalization>

**Observation** (1-2 instances):
- Note for future reference
- "This worked well, watch for recurrence"

**Hypothesis** (3+ instances):
- Draft informal guideline
- Test consciously in next case

**Codification** (validated pattern):
- Create formal documentation
- Include examples and constraints

**Refinement** (ongoing):
- Update based on usage
- Add edge cases

</progressive_formalization>

<workflow>

Loop: Observe → Classify → Validate → Document

1. **Collect signals** — note successes, failures, recurring behaviors
2. **Classify pattern type** — workflow, orchestration, heuristic, anti-pattern
3. **Check evidence threshold** — 3+ instances? Multiple contexts?
4. **Extract quality criteria** — what makes it work?
5. **Document pattern** — name, when, what, why
6. **Test deliberately** — apply consciously, track variance
7. **Refine** — adjust based on feedback

</workflow>

<rules>

ALWAYS:
- Require 3+ instances before codifying
- Validate across multiple contexts
- Document both when to use AND when not to
- Include concrete examples
- Track pattern effectiveness over time

NEVER:
- Codify after single occurrence
- Abstract without evidence
- Ignore context-sensitivity
- Skip validation step
- Assume transferability without testing

</rules>

<references>

**Deep-dive documentation**:
- [signal-types.md](references/signal-types.md) — detailed signal taxonomy
- [pattern-types.md](references/pattern-types.md) — pattern templates and examples

**Related skills**:
- [patternify](../patternify/SKILL.md) — pattern discovery from conversations
- [codebase-analysis](../codebase-analysis/SKILL.md) — uses pattern analysis for code investigation
- [report-findings](../report-findings/SKILL.md) — presenting discovered patterns

</references>

```

### ../root-cause-analysis/SKILL.md

```markdown
---
name: root-cause-analysis
version: 1.0.0
description: This skill should be used when diagnosing failures, investigating incidents, finding root causes, or when "root cause", "diagnosis", "investigate", or "--rca" are mentioned.
---

# Root Cause Analysis

Symptom → hypothesis formation → evidence gathering → elimination → root cause → verified fix.

<when_to_use>

- Diagnosing system failures or unexpected behavior
- Investigating incidents or outages
- Finding the actual cause vs surface symptoms
- Preventing recurrence through understanding
- Any situation where "why did this happen?" needs answering

NOT for: known issues with documented fixes, simple configuration errors, guessing without evidence

</when_to_use>

<discovery_phase>

## Core Questions

| Question | Why it matters |
|----------|----------------|
| What's the symptom? | Exact manifestation of the problem |
| When did it start? | First occurrence, patterns in timing |
| Can you reproduce it? | Consistently, intermittently, specific conditions |
| What changed recently? | Deployments, config, dependencies, environment |
| What have you tried? | Previous fix attempts, their results |
| What are the constraints? | Time budget, what can't be modified |

## Confidence Thresholds

| Level | State | Action |
|-------|-------|--------|
| 0-2 | Symptom unclear or can't reproduce | Keep gathering info |
| 3 | Good context, some gaps | Can start hypothesis phase |
| 4+ | Clear picture | Proceed to investigation |

At level 3+, transition to hypothesis formation. Below level 3, keep gathering context.

</discovery_phase>

<hypothesis_formation>

## Quality Criteria

| Good Hypothesis | Weak Hypothesis |
|-----------------|-----------------|
| Testable | Too broad ("something's wrong") |
| Falsifiable | Untestable |
| Specific | Contradicts evidence |
| Plausible | Assumes conclusion |

## Multiple Working Hypotheses

Generate 2-4 competing theories:
1. List each hypothesis with supporting/contradicting evidence
2. Rank by likelihood (evidence support, parsimony, testability)
3. Design tests to differentiate between them

</hypothesis_formation>

<evidence_gathering>

## Observation Collection

| Category | What to Gather |
|----------|----------------|
| Error manifestation | Exact symptoms, messages, states |
| Reproduction steps | Minimal sequence triggering issue |
| System state | Logs, variables, config at failure time |
| Environment | Versions, platform, dependencies |
| Timing | When started, frequency, patterns |

## Breadcrumb Analysis

Trace backwards from symptom:
1. **Last known good state** — what was working?
2. **First observable failure** — when did it break?
3. **Changes between** — what's different?
4. **Root trigger** — first thing that went wrong

</evidence_gathering>

<hypothesis_testing>

## Test Design

For each hypothesis:
1. **Prediction** — if true, what should we observe?
2. **Test method** — how to verify?
3. **Expected result** — what confirms/refutes?
4. **Time budget** — when to move on?

## Testing Priorities

| Priority | Strategy |
|----------|----------|
| **First** | Quick, non-destructive, local tests |
| **Second** | Most likely causes, common failures |
| **Third** | Edge cases, rare failures |

## Execution Loop

Baseline → Single variable change → Observe → Document → Iterate

</hypothesis_testing>

<elimination_methodology>

Three core techniques:

| Technique | When to Use |
|-----------|-------------|
| **Binary Search** | Large problem space, ordered changes |
| **Variable Isolation** | Multiple variables, need causation |
| **Process of Elimination** | Finite set of possible causes |

See [elimination-techniques.md](references/elimination-techniques.md) for detailed methods.

</elimination_methodology>

<time_boxing>

| Phase | Duration | Exit Condition |
|-------|----------|----------------|
| Discovery | 5-10 min | Questions answered, can reproduce |
| Hypothesis | 10-15 min | 2-4 testable theories ranked |
| Testing | 15-30 min per hypothesis | Confirmed or ruled out |
| Fix | Variable | Root cause addressed |
| Verification | 10-15 min | Fix confirmed, prevention documented |

If stuck beyond 2x estimate → step back, seek fresh perspective, or escalate.

</time_boxing>

<audit_trail>

Log every step:

```
[TIME] PHASE: Action → Result
[10:15] DISCOVERY: Gathered error logs → Found NullPointerException
[10:22] HYPOTHESIS: User object not initialized
[10:28] TEST: Added null check logging → Confirmed user is null
```

Benefits: Prevents revisiting same ground, enables handoff, catches circular investigation.

See [documentation-templates.md](references/documentation-templates.md) for full templates.

</audit_trail>

<common_pitfalls>

Watch for these patterns:

| Trap | Counter |
|------|---------|
| "I already looked at that" | Re-examine with fresh evidence |
| "That can't be the issue" | Test anyway, let evidence decide |
| "We need to fix this quickly" | Methodical investigation is faster |
| Confirmation bias | Actively seek disconfirming evidence |
| Correlation = causation | Test direct causal mechanism |

See [pitfalls.md](references/pitfalls.md) for detailed resistance patterns and recovery.

</common_pitfalls>

<confidence_calibration>

| Level | Indicators |
|-------|------------|
| **High** | Consistent reproduction, clear cause-effect, multiple confirmations, fix verified |
| **Moderate** | Reproduces mostly, strong correlation, single confirmation |
| **Low** | Inconsistent reproduction, unclear correlation, unverified hypothesis |

</confidence_calibration>

<rules>

ALWAYS:
- Gather sufficient context before hypothesizing
- Form multiple competing hypotheses
- Test systematically, one variable at a time
- Document investigation trail
- Verify fix actually addresses root cause
- Document for future prevention

NEVER:
- Jump to solutions without diagnosis
- Trust single hypothesis without testing alternatives
- Apply fixes without understanding cause
- Skip verification of fix
- Repeat same failed investigation steps
- Hide uncertainty about root cause

</rules>

<references>

**Deep-dive documentation**:
- [elimination-techniques.md](references/elimination-techniques.md) — binary search, variable isolation, process of elimination
- [pitfalls.md](references/pitfalls.md) — cognitive biases and resistance patterns
- [documentation-templates.md](references/documentation-templates.md) — investigation logs and RCA reports

**Related skills**:
- [debugging-and-diagnosis](../debugging-and-diagnosis/SKILL.md) — code-specific debugging (loads this skill)
- [codebase-analysis](../codebase-analysis/SKILL.md) — uses for code investigation
- [report-findings](../report-findings/SKILL.md) — presenting investigation results

</references>

```

### ../report-findings/SKILL.md

```markdown
---
name: report-findings
version: 1.0.0
description: This skill should be used when synthesizing multi-source research, presenting findings with attribution, or when "report", "findings", or "synthesis" are mentioned.
---

# Report Findings

Multi-source gathering → authority assessment → cross-reference → synthesize → present with confidence.

<when_to_use>

- Synthesizing research from multiple sources
- Presenting findings with proper attribution
- Comparing options with structured analysis
- Assessing source credibility
- Documenting research conclusions

NOT for: single-source summaries, opinion without evidence, rushing to conclusions

</when_to_use>

<source_authority>

| Tier | Confidence | Types | Use For |
|------|------------|-------|---------|
| **1: Primary** | 90-100% | Official docs, original research, direct observation | Factual claims, guarantees |
| **2: Secondary** | 70-90% | Expert analysis, established publications, official guides | Best practices, patterns |
| **3: Community** | 50-70% | Q&A sites, blogs, wikis, anecdotal evidence | Workarounds, pitfalls |
| **4: Unverified** | 0-50% | Unattributed, outdated, content farms, unchecked AI | Initial leads only |

See [source-tiers.md](references/source-tiers.md) for detailed assessment criteria.

</source_authority>

<cross_referencing>

## Two-Source Minimum

Never rely on single source for critical claims:
1. Find claim in initial source
2. Seek confirmation in independent source
3. If sources conflict → investigate further
4. If sources agree → moderate confidence
5. If 3+ sources agree → high confidence

## Conflict Resolution

When sources disagree:
1. **Check dates** — newer information often supersedes
2. **Compare authority** — higher tier beats lower tier
3. **Verify context** — might both be right in different scenarios
4. **Test empirically** — verify through direct observation if possible
5. **Document uncertainty** — flag if unresolved

## Triangulation

For complex questions, seek alignment across:
- **Official sources** — what should happen
- **Direct evidence** — what actually happens
- **Community reports** — what people experience

All three align → high confidence. Mismatches → investigate the gap.

</cross_referencing>

<comparison_analysis>

Three comparison methods:

| Method | When to Use |
|--------|-------------|
| **Feature Matrix** | Side-by-side capability comparison |
| **Trade-off Analysis** | Strengths/weaknesses/use cases per option |
| **Weighted Matrix** | Quantitative scoring with importance weights |

See [comparison-methods.md](references/comparison-methods.md) for templates and examples.

</comparison_analysis>

<synthesis_techniques>

## Extract Themes

Across sources, identify:
- **Consensus** — what everyone agrees on
- **Disagreements** — where opinions differ
- **Edge cases** — nuanced situations

## Present Findings

1. **Main answer** — clear, actionable
2. **Supporting evidence** — cite 2-3 strongest sources
3. **Caveats** — limitations, context-specific notes
4. **Alternatives** — other valid approaches

</synthesis_techniques>

<confidence_calibration>

| Level | Indicator | Criteria |
|-------|-----------|----------|
| **High** | 90-100% | 3+ tier-1 sources agree, empirically verified |
| **Moderate** | 60-89% | 2 tier-2 sources agree, some empirical support |
| **Low** | Below 60% | Single source or tier-3 only, unverified |

Flag remaining uncertainties even at high confidence.

</confidence_calibration>

<output_format>

Standard report structure:

```markdown
## Summary
{ 1-2 sentence answer }

## Key Findings
1. {FINDING} — evidence: {SOURCE}

## Comparison (if applicable)
{ matrix or trade-off analysis }

## Confidence Assessment
Overall: {LEVEL} {PERCENTAGE}%

## Sources
- [Source](url) — tier {N}

## Caveats
{ uncertainties, gaps, assumptions }
```

See [output-template.md](references/output-template.md) for full template with guidelines.

</output_format>

<rules>

ALWAYS:
- Assess source authority before citing
- Cross-reference critical claims (2+ sources)
- Include confidence levels with findings
- Cite sources with proper attribution
- Flag uncertainties

NEVER:
- Cite single source for critical claims
- Present tier-4 sources as authoritative
- Skip confidence calibration
- Hide conflicting sources
- Omit caveats when uncertainty exists

</rules>

<references>

**Deep-dive documentation**:
- [source-tiers.md](references/source-tiers.md) — detailed authority assessment
- [comparison-methods.md](references/comparison-methods.md) — comparison templates
- [output-template.md](references/output-template.md) — full report structure

**Related skills**:
- [research-and-report](../research-and-report/SKILL.md) — full research workflow (loads this skill)
- [codebase-analysis](../codebase-analysis/SKILL.md) — uses for technical research synthesis
- [pattern-analysis](../pattern-analysis/SKILL.md) — identifying patterns in findings

</references>

```

### references/architecture-analysis.md

```markdown
# 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?

```

### ../pathfinding/references/confidence.md

```markdown
# Confidence

Confidence reflects certainty that you can deliver the requested outcome with the available information.

## Philosophy

Balance two goals:
1. **Gather enough** to deliver quality results
2. **Avoid over-questioning** that frustrates user

Consider:
- **Clarity**: How well-defined is the ask?
- **Risk**: What happens if assumptions are wrong?
- **Complexity**: How many moving parts?
- **Ambiguity**: How many valid interpretations?

## Level Overview

| Bar       | Level | Name         | Internal % |
| --------- | ----- | ------------ | ---------- |
| `░░░░░`   | 0     | **Prepping** | 0–19%      |
| `▓░░░░`   | 1     | **Scouting** | 20–39%     |
| `▓▓░░░`   | 2     | **Exploring**| 40–59%     |
| `▓▓▓░░`   | 3     | **Charting** | 60–74%     |
| `▓▓▓▓░`   | 4     | **Mapped**   | 75–89%     |
| `▓▓▓▓▓`   | 5     | **Ready**    | 90–100%    |

## Phase Transitions

Confidence levels trigger phase transitions. Phases always advance, never regress.

### Phase-Confidence Mapping

| Level | Phase | activeForm |
|-------|-------|------------|
| 0–1 | Prep | "Prepping" |
| 2–3 | Explore | "Exploring" |
| 4 | Clarify | "Clarifying" |
| 5 | Deliver | "Delivering" |

### Rules

1. **No regression**: If confidence drops (4 → 3), stay in current phase
2. **Skip when starting high**: Level 5 start → go directly to Deliver
3. **Phase independence**: Confidence can fluctuate within a phase
4. **Early delivery**: User can request delivery at any phase → add `△ Caveats`

### Edge Cases

**High start**: Clear requirements → Start at Ready, go directly to Deliver

**Confidence drop**: Reach Mapped (4), enter Clarify, then realize gap (drops to 3) → Stay in Clarify, ask targeted questions

**Rapid ascent**: Start at Exploring (2) → one answer jumps to Mapped (4) → next to Ready (5) → transition through phases quickly

### Level 0: Prepping `░░░░░`

**Phase**: Prep

**When**: Request completely unclear, no domain context, pure guessing

**Ask**: Scope, constraints, goals, background

**Example**: "Make it better" with no context about what "it" is.

### Level 1: Scouting `▓░░░░`

**Phase**: Prep

**When**: Vague direction, domain clear but specifics aren't

**Ask**: What system? How big? What's in place?

**Example**: "Improvements to the dashboard" — which kind?

### Level 2: Exploring `▓▓░░░`

**Phase**: Explore

**When**: General area understood, lack critical details, multiple approaches possible

**Ask**: Which approach? What about X? What matters most? Speed vs quality?

**Example**: "Authentication" — method, scale, existing system unknown.

### Level 3: Charting `▓▓▓░░`

**Phase**: Explore

**When**: Reasonable understanding, could deliver with notable assumptions

**Do**:
1. Summarize (3 bullets max)
2. Ask 2–3 targeted questions toward level 4–5
3. If user proceeds early → add `△ Caveats`

**Example**: OAuth login — general approach known, need providers + fallback strategy.

### Level 4: Mapped `▓▓▓▓░`

**Phase**: Clarify

**When**: Solid understanding, few clarifications would reach Ready, low risk

**Do**: Offer choice — "Can proceed, but 1–2 more questions would reach full confidence. Continue or deliver now?"

**Example**: New API endpoint — data model understood, need error handling approach.

### Level 5: Ready `▓▓▓▓▓`

**Phase**: Deliver

**When**: Clear understanding, no major assumptions, minimal risk

**Do**: Produce artifact immediately, succinct next steps, no more questions unless something emerges

**Example**: "Add logout button to header" — clear, specific, low-risk.

## Special Cases

### Starting Confidence

Start honest. Don't artificially start low if the request is clear.

- **Clear request** → level 4–5
- **Vague request** → level 0–2

### Delivering Below Level 5

User wants quick delivery at lower confidence:

1. Confirm they want to proceed
2. Add `△ Caveats` section
3. List assumptions, concerns, unknowns

### Calibration

- Deliver at 5, goes well → calibrated
- Deliver at 5, miss the mark → overconfident
- Stay at 0–2 too long → underconfident

## Tuning

Percentage boundaries can adjust based on risk tolerance:
- **Higher risk tolerance** → shift boundaries down
- **Lower risk tolerance** → shift boundaries up

```

### ../../shared/rules/FORMATTING.md

```markdown
# Formatting Conventions

## Markdown in Instructions

Avoid `**bold**` and other emphasis markers in skill/instruction text unless explicitly formatting output. Claude doesn't need visual emphasis to understand importance — the words themselves convey it.

**Use markdown when**: formatting actual output, examples, or user-facing content
**Skip markdown when**: writing instructions, rules, or guidance for Claude

## Concision Principle

Sacrifice grammar for concision — drop articles, filler words, verbose phrases. But don't strip meaning or context. Goal is density, not minimalism. If removing a word makes the instruction ambiguous, keep it.

Good: "Ask one question, wait for response"
Bad: "Ask question wait response"

## Variables and Placeholders

**Variables** — all caps, no spaces, curly braces:
- `{VARIABLE}` — concrete placeholder to be replaced
- Examples: `{N}`, `{REASON}`, `{BAR}`, `{NAME}`, `{FILE_PATH}`

**Instructional prose** — lowercase, spaces inside braces:
- `{ description of what goes here }` — guidance for what to fill in
- Examples: `{ question text }`, `{ why it matters }`, `{ if needed }`

## XML Tags in Skills

Use XML tags for structural sections in skill files:
- `<when_to_use>` — trigger conditions
- `<confidence>` — confidence levels/tracking
- `<phases>` — workflow phases
- `<workflow>` — core process loop
- `<rules>` — always/never constraints
- `<references>` — links to supporting docs

Keep content inside tags terse. Sacrifice grammar for concision where meaning is preserved.

**GitHub rendering**: Add blank lines after opening tags and before closing tags. Without them, content renders incorrectly on GitHub.

```markdown
<!-- Good -->
<rules>

- First rule
- Second rule

</rules>

<!-- Bad — won't render properly on GitHub -->
<rules>
- First rule
- Second rule
</rules>
```

## Markdown Tables

Use markdown tables for structured data. Ensure the table is properly formatted with the correct number of columns and rows.

```markdown
| Column 1 | Column 2 | Column 3 |
| -------- | -------- | -------- |
| Data 1   | Data 2   | Data 3   |
```

Ensure pipes are properly aligned with spaces surrounding text or hyphens, at least between the header and separator rows. If pipes are used within a cell, ensure they are properly escaped.

## Indicators

Prefer ASCII/Unicode over emoji for terminal output (Claude Code, CLI, interactive sessions). Emoji acceptable in docs or user-facing content where rendering is reliable.

### Progress

- `░` — empty (light shade)
- `▓` — filled (medium shade)
- Example: `▓▓▓░░` = 3/5
- Use for confidence, completion, capacity — anything with discrete levels

### Severity

Escalating:

- `◇` — minor/informational
- `◆` — moderate/warning
- `◆◆` — severe/blocking
- Use for pushback, risk, alerts, uncertainty levels

### Caveats

- `△` — incomplete/uncertain (warning triangle U+25B3)
- **Mid-stream**: `△` + description — flags issue for immediate attention
- **At delivery**: `△ Caveats` — summary section of gaps, unknowns, assumptions, concerns, deferred items

### Checkmarks

- `✓` — completed/decided (U+2713)
- Use for "Decisions Made:" lists, completed items, confirmed choices
- Example:

  ```text
  Decisions Made:
  ✓ /simplify offers two modes: quick (skill) vs deep (agent)
  ✓ Agent returns: complexity identified + alternatives + escalation level
  ✓ Uses ◇/◆/◆◆ indicators from complexity-analysis skill
  ```

### Emphasis

Append to text:

- `★` — recommended/preferred

## Interactive Questions

For multi-option questions in skills:

- Use `EnterPlanMode` — enables keyboard navigation
- **Prose above tool**: context, "why it matters"
- **Inside tool**: options with inline recommendation marker
- Always include escape hatch: "5. Something else — { brief prompt }"

### Inline Recommendations

Mark recommended option inline with `[★]` + emphasized rationale:

```text
1. Google only [★] — simplest, highest coverage *good starting point, expand later*
2. Google + GitHub — covers consumer and developer users
3. Google + GitHub + Microsoft — comprehensive, more maintenance
```

Pattern: `N. Option name [★] — brief description *why recommended*`

- `[★]` visually distinguishes the recommendation
- `*italicized rationale*` provides quick reasoning
- Everything scannable in one place

## TodoWrite

Give todos friendly, context-specific descriptions instead of generic phase names. The description should tell the user what's actually happening.

**Prefer**:

```text
- [x] Consider skills to load
- [ ] Prep auth system requirements
- [ ] Explore authentication approaches
- [ ] Clarify platform and fallback needs
- [ ] Deliver implementation plan
```

**Avoid**:

```text
- [ ] Gather Context
- [ ] Synthesize Requirements
- [ ] Provide Deliverables
```

## Markdown Links

Use short aliases for readability. Keep paths intact.

Prefer: `[filename.md](path/to/filename.md)`
Avoid: `[path/to/filename.md](path/to/filename.md)`

```text
# Good
- [confidence.md](references/confidence.md)
- [FORMATTING.md](../../shared/rules/FORMATTING.md)

# Avoid
- [references/confidence.md](references/confidence.md)
- [../../shared/rules/FORMATTING.md](../../shared/rules/FORMATTING.md)
```

```