/codebase-analyzer

name: codebase-analyzer
promoted_to: codebase-overview
description: "Statistical rule discovery from Go codebase patterns."
user-invocable: false
allowed-tools:
  - Read
  - Write
  - Bash
  - Grep
  - Glob
  - Edit
  - Task
context: fork
routing:
  triggers:
    - "analyze codebase"
    - "discover patterns"
    - "style vector"
    - "code cartographer"
    - "pattern frequency"
    - "structural metrics"
  category: analysis
  pairs_with:
    - codebase-overview
    - go-patterns

Codebase Analyzer Skill

Statistical rule discovery through measurement of Go codebases. Python scripts count patterns to avoid LLM training bias, then statistics are interpreted to derive confidence-scored rules. The core principle is **Measure First, Interpret Second** -- what IS in the code is the local standard, not what an LLM thinks "should be" there.

Reference Loading

Load these files when the corresponding signals appear:

| Signal | Load | |--------|------| | Understanding the three lenses (Consistency, Signature, Idiom) | `references/three-lenses.md` | | Worked examples, phase banners, error catalog, reconciliation matrix | `references/phase-details.md` | | Full 100-metric catalog across 25 categories | `references/metrics-catalog.md` | | Additional real-world analysis workflows | `references/examples.md` |

Reference Loading Table

| Signal | Load These Files | Why | |---|---|---| | worked analyses: single Go service, multi-repo comparison, pattern adoption and evolution tracking | `examples.md` | Loads detailed guidance from `examples.md`. | | computing the 100 metrics across 25 categories | `metrics-catalog.md` | Loads detailed guidance from `metrics-catalog.md`. | | phase banners, reconciliation matrix, rule format | `phase-details.md` | Loads detailed guidance from `phase-details.md`. | | understanding the measure-don't-read statistical approach | `three-lenses.md` | Loads detailed guidance from `three-lenses.md`. |

Instructions

Phase 1: CONFIGURE

**Goal**: Validate target and select analyzer variant.

Read and follow the repository's CLAUDE.md before doing anything else -- project instructions override default behaviors.

**Step 1: Validate the target**

• Confirm path points to a Go repository root with .go files
• Check for standard structure (cmd/, internal/, pkg/)
• Verify sufficient file count: 50+ files for meaningful rules, 100+ ideal. Below 50 files, statistics produce high variance -- patterns that look consistent may be coincidence. For small repos, combine analysis across multiple team repos rather than treating thin data as definitive.

**Step 2: Select cartographer variant**

| Variant | Script | Metrics | Use When | |---------|--------|---------|----------| | Omni (recommended) | `cartographer_omni.py` | 100 across 25 categories | Full codebase profiling | | Basic | `cartographer.py` | ~15 categories | Quick pattern overview | | Ultimate | `cartographer_ultimate.py` | 6 focused categories | Performance pattern detection |

**Step 3: Verify environment**

• Python 3.7+ available
• No external dependencies needed (uses only Python standard library)
• Output directories exist or can be created

See `references/phase-details.md` for the CONFIGURE banner template.

**Gate**: Target directory exists, contains 50+ Go files, variant selected. Proceed only when gate passes.

Phase 2: MEASURE

**Goal**: Run statistical analysis scripts. Pure measurement -- no interpretation yet.

This phase is strictly mechanical. Scripts count and measure; keep interpretation separate from data collection. Combining measurement with interpretation introduces LLM training bias -- the model reports what "should be" instead of what IS. Run scripts first, interpret the numbers second, always as separate steps.

Automatically filter vendor/, testdata/, and generated code (files with "Code generated by..." markers) to avoid polluting statistics with external patterns.

**Step 1: Execute the cartographer**

python3 ${CLAUDE_SKILL_DIR}/scripts/cartographer_omni.py /path/to/go/repo
# Or for quick overview: python3 ${CLAUDE_SKILL_DIR}/scripts/cartographer.py /path/to/go/repo

Always run the cartographer scripts for measurement; reserve LLM interpretation for Phase 3. When an LLM sees `return err` it may report "not wrapping errors properly" even if that IS the local standard. The scripts produce deterministic, reproducible counts; the LLM's role begins at interpretation in Phase 3.

**Step 2: Verify output integrity**

• Confirm JSON output is valid and complete
• Check file count matches expectations (no vendor pollution)
• Verify all three lenses produced data
• Confirm derived_rules section exists in output

**Step 3: Check for data quality issues**

• File count suspiciously high? Vendor code may be included
• File count suspiciously low? Subdirectories may be missed
• All percentages near 50%? May indicate mixed codebase or insufficient data

See `references/phase-details.md` for the MEASURE banner template.

**Gate**: Script completed without errors, JSON output is valid, file count is reasonable. Proceed only when gate passes.

Phase 3: INTERPRET

**Goal**: Derive rules from statistics. This is where LLM interpretation happens -- AFTER measurement is complete.

Report facts and show complete statistics rather than describing them. Report facts without editorializing about code quality -- the numbers speak for themselves.

**Step 1: Review the three lenses**

| Lens | Question | Measures | |------|----------|----------| | Consistency (Frequency) | "How often do they use X?" | Imports, test frameworks, logging, modern features | | Signature (Structure) | "How do they name/structure things?" | Constructors, receivers, parameter order, variables | | Idiom (Implementation) | "How do they implement patterns?" | Error handling, control flow, context usage, defer |

For detailed lens explanations, see `references/three-lenses.md`.

**Step 2: Extract rules by confidence**