• 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.

• 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.

• 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).

• 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

• 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

• 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...
===============================================================

**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

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

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

• JSON output valid
• File count reasonable (no vendor pollution)
• All three lenses have data
• No unexpected zeros in major categories

MEASURE complete. Proceeding to INTERPRET...

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

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

**Step 4: Recommend next steps**
- 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

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

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

1. [Specific recommendation]
2. [Specific recommendation]
3. [Specific recommendation]

DELIVER complete. Analysis finished.

**Gate**: JSON report saved, rules document generated, next steps documented. Analysis complete.

---

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

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

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

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

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)

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-Rationalization - Prevents shortcut rationalizations
• Verification Checklist - Pre-completion checks

• ${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

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