Codebase Analyzer Skill

Operator Context

Hardcoded Behaviors (Always Apply)

• CLAUDE.md Compliance: Read and follow repository CLAUDE.md files before execution. Project instructions override default behaviors.
• Over-Engineering Prevention: Scripts perform pure statistical measurement only. No feature additions beyond counting patterns. No speculative metrics or flexibility that was not requested.
• Measurement-Only Analysis: Scripts count and measure; NEVER interpret or judge code quality during data collection phase. The LLM is a calculator, not a judge.
• No Training Bias: Analysis MUST avoid LLM interpretation of "good" vs "bad" patterns during measurement. What IS in the code is the local standard.
• Confidence Gating: Only derive rules from patterns with >70% consistency. Below that threshold, report statistics without creating rules.
• Separate Measurement from Interpretation: Run scripts first (mechanical), then interpret statistics second (analytical). Never combine these steps.

Default Behaviors (ON unless disabled)

• Communication Style: Report facts without self-congratulation. Show complete statistics rather than describing them. Be concise but informative.
• Temporary File Cleanup: Analysis scripts do not create temporary files (single-pass processing). Any debug outputs or iteration files should be removed at completion.
• Verbose Output: Display summary statistics to stderr, full JSON to stdout or file.
• Confidence Thresholds: HIGH (>85%), MEDIUM (70-85%), below 70% not extracted as rule.
• Vendor Filtering: Automatically skip vendor/, testdata/, and generated code to avoid polluting statistics with external patterns.

Optional Behaviors (OFF unless enabled)

• Cross-Repository Analysis: Compare patterns across multiple repos (requires explicit request).
• Historical Tracking: Re-analyze same repo over time to track pattern evolution (requires explicit request).
• Custom Metric Addition: Add new measurement categories beyond the 100 standard metrics (requires explicit request).

What This Skill CAN Do

• Extract implicit coding rules through statistical analysis of Go codebases
• Measure 100 metrics across 25 categories using Python scripts
• Derive confidence-scored rules from pattern frequency data
• Produce a 10-dimensional Style Vector quality fingerprint (0-100 scores)
• Discover shadow constitution rules (linter suppressions teams accept)
• Compare patterns across multiple repositories for team-wide standards

What This Skill CANNOT Do

• Judge code quality subjectively (measures patterns, not "good" vs "bad")
• Analyze non-Go codebases (scripts are Go-specific)
• Derive rules from codebases with fewer than 50 Go files (insufficient sample)
• Replace code review or linting (produces rules, not enforcement)
• Skip measurement and rely on LLM "reading" the code

Instructions

Phase 1: CONFIGURE (Do NOT proceed without validated 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)

cartographer_omni.py

cartographer.py

cartographer_ultimate.py

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

===============================================================
 PHASE 1: CONFIGURE
===============================================================

 Target Repository:
   - Path: [/path/to/repo]
   - Go Files: [N files found]
   - Structure: [cmd/ | internal/ | pkg/ | flat]

 Variant Selected: [Omni | Basic | Ultimate]
 Reason: [why this variant]

 Validation:
   - [ ] Path exists and contains .go files
   - [ ] File count >= 50 (actual: N)
   - [ ] Python 3.7+ available
   - [ ] Output directory writable

 CONFIGURE complete. Proceeding to MEASURE...
===============================================================

Phase 2: MEASURE (Do NOT interpret during this phase)

# TODO: scripts/cartographer_omni.py not yet implemented
# Manual alternative: use grep/find to count patterns across Go files
# Example: count error wrapping patterns
grep -rn 'fmt.Errorf.*%w' ~/repos/my-project --include="*.go" | wc -l
# Example: count constructor patterns
grep -rn 'func New' ~/repos/my-project --include="*.go" | wc -l

• 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

• 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

===============================================================
 PHASE 2: MEASURE
===============================================================

 Script Executed: [cartographer_omni.py (not yet implemented — use manual pattern counting)]
 Target: [/path/to/repo]

 Results:
   - Files analyzed: [N]
   - Total lines: [N]
   - Categories measured: [N of 25]
   - Derived rules: [N auto-extracted]

 Data Quality:
   - [ ] JSON output valid
   - [ ] File count reasonable (no vendor pollution)
   - [ ] All three lenses have data
   - [ ] No unexpected zeros in major categories

 Output saved to: [path/to/output.json]

 MEASURE complete. Proceeding to INTERPRET...
===============================================================

Phase 3: INTERPRET (Now the LLM analyzes)

references/three-lenses.md

• 10 composite scores (0-100): Consistency, Modernization, Safety, Idiomaticity, Documentation, Testing Maturity, Architecture, Performance, Observability, Production Readiness
• Identify strengths (scores >75) and gaps (scores <50)
• Note shadow constitution entries (accepted linter suppressions)

• Pattern confirmed across multiple lenses = higher confidence
• Pattern in one lens only = standard confidence
• Contradictions between lenses = investigate further

Phase 4: DELIVER (Do NOT mark complete without artifacts)

cartography_data/{repo_name}_cartography.json

derived_rules/{repo_name}_rules.md

## Rule: [Statement]
**Confidence**: HIGH/MEDIUM
**Evidence**: [X% consistency across N occurrences]
**Category**: [error_handling | naming | control_flow | architecture | ...]
**Lens**: [Consistency | Signature | Idiom | Multiple]

## Style Vector Summary
| Dimension | Score | Assessment |
|-----------|-------|------------|
| Consistency | [0-100] | [Strength/Gap/Neutral] |
| Modernization | [0-100] | [Strength/Gap/Neutral] |
| ... | ... | ... |

• Compare with pr-miner data if available (explicit vs implicit rules)
• Suggest CLAUDE.md updates for high-confidence rules
• Identify golangci-lint rules that could enforce discovered patterns
• Suggest quarterly re-analysis schedule

===============================================================
 PHASE 4: DELIVER
===============================================================

 Artifacts:
   - [ ] JSON report: [path]
   - [ ] Rules document: [path]
   - [ ] Style Vector summary: [included in rules doc]

 Results Summary:
   - HIGH confidence rules: [N]
   - MEDIUM confidence rules: [N]
   - Observations (below threshold): [N]
   - Style Vector overall: [strong/mixed/weak]

 Next Steps:
   1. [Specific recommendation]
   2. [Specific recommendation]
   3. [Specific recommendation]

 DELIVER complete. Analysis finished.
===============================================================

Complementary Skills

Reconciliation Matrix

Examples

Example 1: Single Repository Analysis

1. Validate target has 100+ Go files (CONFIGURE)
2. Run pattern counting against the repo (MEASURE)
3. Extract rules from statistics: error wrapping 89%, guard clauses 5.2x, New{Type} 94% (INTERPRET)
4. Save JSON report and rules document (DELIVER) Result: 30+ rules extracted with confidence levels, Style Vector produced

Example 2: Team-Wide Standards Discovery

1. Validate all target repos, confirm 50+ files each (CONFIGURE)
2. Run cartographer on each repo separately (MEASURE)
3. Cross-reference patterns: error wrapping 87-91% across all repos = team standard (INTERPRET)
4. Produce team-wide rules document with per-repo breakdowns (DELIVER) Result: Team-wide standards with cross-repo evidence

Example 3: Onboarding New Developer

1. Identify main team repos, validate Go file counts (CONFIGURE)
2. Run omni-cartographer on primary service (MEASURE)
3. Extract top 10 HIGH confidence rules as onboarding checklist (INTERPRET)
4. Produce concise rules doc focusing on error handling, naming, and control flow (DELIVER) Result: Evidence-based onboarding guide with concrete examples from actual codebase

Error Handling

Error: "No Go files found"

1. Verify path points to repository root with

   ls *.go

   or

   find . -name "*.go" | head

2. If Go files are nested, point to parent directory
3. Confirm vendor/ is not the only directory containing Go files

Error: "No rules derived"

1. Check file count -- if <50, combine analysis across multiple repos from same team
2. If >50 files but no rules, team genuinely lacks consistent patterns
3. Lower threshold to 60% to find emerging patterns (note reduced confidence)

Error: "Statistics dominated by vendor/generated code"

1. Verify scripts are filtering vendor/, testdata/, and _test files for core patterns
2. If non-standard structure, analyze specific directories manually
3. Check for generated code markers (Code generated by...) and exclude those files

Anti-Patterns

Anti-Pattern 1: LLM Reading Instead of Script Measuring

return err

Anti-Pattern 2: Rules from Low-Confidence Patterns

Anti-Pattern 3: Analyzing Insufficient Sample Size

Anti-Pattern 4: One-Time Analysis Without Follow-Up

Anti-Pattern 5: Mixing Measurement and Interpretation

References

• Anti-Rationalization - Prevents shortcut rationalizations
• Verification Checklist - Pre-completion checks

Domain-Specific Anti-Rationalization

Reference Files

• ${CLAUDE_SKILL_DIR}/references/three-lenses.md

  : Detailed explanation of the three analysis lenses

• ${CLAUDE_SKILL_DIR}/references/examples.md

  : Real-world analysis examples and workflows

• ${CLAUDE_SKILL_DIR}/references/metrics-catalog.md

  : Complete 100-metric catalog across 25 categories

Prerequisites

• Python 3.7+
• Go codebase to analyze (50+ files recommended)
• No external dependencies (uses only Python standard library)