notque/vexjoy-agent / skills/analysis/assessment
assessment
VerifiedAssessment: read-only inspection, codebase overview, value analysis, health checks, ADR consultation, decision analysis, multi-perspective critique.
references/codebase-overview/statistical-metrics-catalog.md
View on GitHub# Codebase Analyzer: 100 Metrics Catalog
Complete reference for the Omni-Cartographer's 25 categories and 100 individual metrics across three phases.
## Phase 1: Tactical Patterns (50 metrics)
### Core Categories (Original Omni, 25 metrics)
**1. Shadow Constitution** (linter suppressions)
- errcheck suppressions
- gosec suppressions
- staticcheck suppressions
**2. Context Hygiene**
- context.Background() in cmd/test locations
- context.Background() in business logic
- context.TODO() usage
**3. Time Management**
- time.Now() direct usage
- Clock interface patterns
**4. Dangerous Functions**
- panic usage
- log.Fatal usage
- init function usage
- os.Exit usage
**5. Modern Go Adoption**
- any vs interface{}
- slices package usage
- maps package usage
- cmp package usage
- min/max builtins
**6. Failure modes**
- Manual contains loops
- Manual deduplication
- Float conversions
**7. Project Architecture**
- cmd/ structure
- internal/ structure
- pkg/ structure
**8. Constructor Patterns**
- New prefix usage
- Create prefix usage
- Must prefix usage
- Functional options
**9. Error Handling**
- %w wrapping frequency
- Error message style (lowercase vs uppercase)
- errors.Is/As usage
**10. Logging**
- Library usage (logrus/zap/slog)
- Log levels distribution
- Structured logging adoption
**11. Testing**
- Framework adoption (ginkgo/testify/standard)
- Table-driven test patterns
**12. Core Patterns**
- Struct initialization style
- Slice allocation patterns
- Receiver types (value vs pointer)
- Mutex usage patterns
### Phase 1 New Categories (25 metrics)
**13. Extended Naming Dialects** (10 metrics)
- Getter style: GetName() vs Name()
- ID convention: ID vs Id, UUID vs Uuid
- Acronym casing: URL vs Url, HTTP vs Http, JSON vs Json, API vs Api
- Constant style: SCREAMING_SNAKE vs CamelCase
- Error variable naming: err vs error vs e
- Boolean prefixes: should/will/enable
- Type suffix usage: TypeUser vs UserType
**14. Control Flow Flavor** (7 metrics)
- Guard clauses vs nested ifs
- Switch vs if-else chains
- Loop styles: for-range vs classic for vs infinite vs condition
- Flow control: break/continue/goto
- Defer patterns: immediate vs named vs cleanup
- Return style: naked vs with values
**15. API and Interface Design** (4 metrics)
- String concatenation: + vs Sprintf vs Builder vs Join
- Zero value usage: explicit initialization patterns
- Enum styles: iota vs string constants
- Optional parameters: functional options vs variadic
**16. Observability Extended** (4 metrics)
- Log structure: JSON vs key=value vs plain
- HTTP status style: named constants vs magic numbers
- Metric naming: snake_case vs CamelCase (Prometheus)
- Error codes: const vs string
## Phase 2: Architectural Patterns (25 metrics)
**17. Interface Topology** (3 metrics)
- Interface sizes: small (<3 methods), medium (3-7), large (8+)
- Interface composition: embedded interfaces
- Interface parameters: interface-typed function params
**18. Configuration Strategy** (4 metrics)
- Config sources: env vars vs flags vs Viper
- Environment variable patterns: with/without defaults
- Flag patterns: flag package usage
- Config structs: configuration type definitions
**19. Dependency Injection** (3 metrics)
- Constructor DI: interface params in constructors
- Interface dependencies: interface-typed struct fields
- Factory patterns: factory function usage
**20. Lifecycle Management** (4 metrics)
- Lifecycle methods: Start/Stop/Close/Run/Shutdown
- Shutdown patterns: graceful shutdown with context
- Cleanup patterns: resource cleanup
- Health checks: health/readiness endpoints
**21. Package Organization** (2 metrics)
- Package naming: singular vs plural
- Package patterns: package structure analysis
**22. Architectural Patterns** (3 metrics)
- Arch patterns: Repository/Service/Handler/Controller
- Middleware patterns: middleware functions and chains
- Layer separation: domain entities vs DTOs
## Phase 3: Style Vector (10 composite scores, 0-100)
**23. Consistency Score**: Pattern uniformity (struct literals, receivers, naming)
**24. Modernization Score**: Go 1.21+ adoption (any, slices, maps, min/max)
**25. Safety Score**: Avoidance of dangerous patterns (panic, fatal, embedded mutexes)
**26. Idiomaticity Score**: Adherence to Go conventions
**27. Documentation Score**: Godoc coverage and quality
**28. Testing Maturity**: Test quality, patterns, and coverage
**29. Architecture Score**: Layering, interface design, separation of concerns
**30. Performance Score**: Efficient pattern usage (prealloc, Builder, failure modes)
**31. Observability Score**: Logging, metrics, structured telemetry
**32. Production Readiness**: Lifecycle management, graceful shutdown, health checks
## Cartographer Versions
> **Note**: The assessment skill ships all three cartographers in `scripts/` (`~/.claude/skills/assessment/scripts/` when installed). Each takes a repository path and `--output <file>`.
### Basic Cartographer (`cartographer.py`)
- **Metrics**: ~15 categories, basic patterns
- **Use Case**: Quick analysis, understanding core patterns
- **Rules Extracted**: 5-10 rules
### Ultimate Cartographer (`cartographer_ultimate.py`)
- **Metrics**: 6 focused categories (keyed structs, slice prealloc, receivers, mutexes)
- **Use Case**: Performance-critical pattern detection
- **Rules Extracted**: 2-5 rules (very focused)
### Omni-Cartographer (`cartographer_omni.py`) -- RECOMMENDED
- **Metrics**: 25 categories, 100 individual metrics
- **Use Case**: Complete codebase DNA profiling, PR review automation, quality tracking
- **Rules Extracted**: 30-40+ rules
- **Phases**: Tactical patterns + Architectural patterns + Style Vector (10-dimensional quality fingerprint)
## Output Structure
The cartographer generates a comprehensive statistical report:
```json
{
"metadata": {
"repo_name": "your-project",
"total_files": 127,
"total_lines": 15432,
"analysis_date": "2025-11-20"
},
"lens_1_consistency": {
"top_dependencies": { ... },
"test_framework_usage": { ... },
"test_framework_percentages": { ... }
},
"lens_2_structure": {
"constructor_patterns": { ... },
"constructor_percentages": { ... },
"receiver_naming": { ... }
},
"lens_3_implementation": {
"error_handling": { ... },
"error_handling_percentages": { ... },
"context_usage": { ... },
"defer_patterns": { ... }
},
"control_flow": {
"guard_clauses": 234,
"else_blocks": 45,
"guard_clause_ratio": 5.2
},
"derived_rules": [
{
"category": "error_handling",
"rule": "All errors must be wrapped using fmt.Errorf with %w verb",
"evidence": "89% consistency across 176 error checks",
"confidence": "HIGH"
}
]
}
```
## Derived Rule Thresholds
Rules are automatically derived when statistical evidence meets these thresholds:
| Confidence | Threshold | Enforcement |
|------------|-----------|-------------|
| HIGH | >85% consistency | Enforce as hard rule |
| MEDIUM | 70-85% consistency | Prefer this pattern, accept exceptions |
| Below 70% | Not extracted | No rule (inconsistent) |
## Typical Analysis Results
**Phase 1 - Tactical Patterns**:
- Naming Voice: ID not Id, err not error, ALL_CAPS acronyms
- Control Flow: Guard clauses percentage, switch over if-else usage
- API Design: String formatting preferences
- Rules Extracted: ~27 rules typical
**Phase 2 - Architectural Patterns**:
- Config Pattern: Environment variables vs flag usage
- Interface Segregation: Percentage of small interfaces (<3 methods)
- Lifecycle Management: Graceful shutdown, health checks
- Rules Extracted: +6 architectural rules typical
**Phase 3 - Style Vector** (Overall Quality Score):
- Dimensions: Documentation, Idiomaticity, Consistency, Production Readiness
- Common Gaps: Performance (slice preallocation, strings.Builder usage)
- Modernization: Go 1.21+ adoption ("any" vs "interface{}")
- Actionable Insights: Specific improvement areas ranked by impact
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |