code-quality-assessment

REPORT_FILE = specs/architecture/code_quality_assessment.md

Target directories: If the target directory for REPORT_FILE does not exist, create it. The assessment is the first artifact that justifies the directory's existence.

Recommended Tools: Make sure you've read ~/§BRAND_GLOBAL_DIRNAME§/AGENT_TOOLS.md list_directory_tree and codebase_search (fast and token-efficient semantic search) may be specifically useful.

Quality is not a binary. Measure it, grade it, and direct investment where it will compound.

Invoked for: periodic health checks, pre-refactoring assessment, onboarding orientation, or explicit code quality evaluation.

---

Process

Metrics Collection → Subsystem Analysis → Synthesis → Recommendations

Templates anchor cognition. Complete each phase before the next. The skill is a measurement framework to apply to what you found, not boxes to fill with platitudes.

Report format: See references/report-format.md for the output template.

---

Modes

Phase applicability:

Mode selection (first match wins):

1. User explicitly requests Targeted → Targeted Assessment
2. User explicitly requests Reassessment → Reassessment
3. User explicitly requests Quick Health Check → Quick Health Check
4. REPORT_FILE exists → Enrichment
5. No existing report → Full Assessment

Full Assessment

Use complete process: Phase 1 → Phase 2 → Phase 3 → Phase 4.

Time Budget: Phase 1 (Metrics) ~30% of effort. Phase 2 (Subsystem Analysis) ~40%. Phases 3+4 (Synthesis + Recommendations) ~30%. Most missed findings come from rushed metrics collection — especially the File Size Distribution scan. If you're tempted to skip ahead, you're under-investing in discovery.

Pairing checkpoint: After Phase 1, present the Metrics Dashboard and identified subsystems before proceeding to Phase 2. This catches scope gaps early (missed languages, wrong LOC counts, missing subsystems).

Default output: REPORT_FILE (if not specified and doesn't exist yet).

Targeted Assessment

Scope to named subsystems only. Collect metrics only for the targeted components.

1. Scope: Confirm which subsystems/directories to assess
2. Metrics: Collect Phase 1 metrics scoped to targeted paths only
3. Analysis: Full Phase 2 for targeted subsystems only
4. Output: If REPORT_FILE exists, update targeted sections within it. If not, create a partial report covering only assessed subsystems.

Reassessment

Requires existing REPORT_FILE.

1. Collect fresh metrics (full Phase 1)
2. For each subsystem, compare current metrics against previous
3. For each previous finding, verify: still relevant? severity changed? resolved?
4. Update ratings and grade
5. Highlight what changed. Tag changes: *(reassessment YYYY-MM-DD)*

Enrichment

Same anti-anchoring protocol as the software-architecture-review skill.

First check: Verify REPORT_FILE exists. If it doesn't, this is Full Assessment, not Enrichment.

Header check (BEFORE discovery): Read REPORT_FILE until you find the Mode: line to extract:

• Pass number (e.g., "Mode: Enrichment (pass 3)")
• Previous lens from header Your pass is N+1. Your lens continues the rotation from the previous lens. ⚠️ STOP as soon as you have the Mode line. Do NOT scroll down or read findings.

⚠️ CRITICAL: You MUST NOT read REPORT_FILE findings until Step 2. Reading findings early causes anchoring — you'll confirm existing findings instead of discovering new ones.

Process:

1. Independent Analysis (Phase 1 + Phase 2) — Complete as if no report exists. Explore the codebase fresh. Hold findings in memory. Do not read the existing report.

2. Merge Phase — Only now read REPORT_FILE. Compare your fresh findings against it.

3. Verification — For each finding in the existing report, verify:

   • Still accurate? (code may have changed)
   • Still relevant? (context may have shifted)
   • Severity still appropriate?
   • Mark each as: ✓ verified, ✗ stale, or ~ adjusted

4. Gap Analysis — List:

   • New findings from fresh pass not in existing report
   • Existing findings your fresh pass missed (and why)

5. Update — Revise REPORT_FILE with:

   • New findings added, tagged *(pass N)* or *(pass N, [lens] lens)*
   • Stale findings removed or marked resolved
   • Severity adjustments where warranted
   • Updated date and metrics in header

Time Budget: Independent Analysis (step 1) should be at least as thorough as merge + verification combined.

Lens Rotation

Each enrichment pass uses a different primary lens. Continue from the previous pass's lens.

Lenses:

1. Complexity — LOC, function length, god classes/scripts, cyclomatic complexity, design-level complexity patterns
2. Test Coverage — Test gaps, untested critical paths, test quality patterns
3. Dependencies — Dependency count, staleness, vendoring, transitive depth
4. Documentation — Doc coverage, staleness risk, spec-code drift
5. CI/Build — Pipeline completeness, enforcement gaps, build hygiene

Rotation order: Complexity → Dependencies → CI/Build → Test Coverage → Documentation → (wrap to Complexity)

The first 3 passes cover the highest-value lenses (Complexity, Dependencies, CI/Build) as primary.

How to apply: During Phase 1+2, start with your primary lens. Spend ~40% of discovery time on it before broadening. The leading lens gets deepest attention while context is fresh.

Complexity lens — systematic scan: When Complexity is your primary lens:

1. Structural scan (start here): Run the LOC scan from Phase 1.3. Flag ALL files >500 LOC as potential god classes. For each, investigate before merge phase.

2. Design-level scan (after structural): For each complex function or file identified, ask "why is this complex?" before recommending how to fix it:

   • Boolean-flag dispatch: Function resolves a type/variant into boolean flags, then threads them through multiple phases. Fix: strategy/polymorphism, not extraction.
   • Imperative ceremony: Repetitive code that follows a pattern but isn't expressed as data. Fix: declarative definitions + loop, not file split.
   • Responsibility mixing: File contains unrelated concerns sharing no state. Fix: file split (this is the one case where extraction IS the right answer).
   • Deep nesting: Complex conditionals that could be flattened. Fix: early returns, guard clauses, or table-driven dispatch.

   The structural scan finds where complexity lives. The design-level scan identifies what kind of complexity it is. Different kinds need different remedies — recommending extraction for a design problem addresses the symptom, not the cause.

Enrichment Iteration Guidance

Recommended: Run enrichment 3 times for solid coverage. Additional passes provide diminishing returns.

⚠️ MANDATORY after 3+ passes: If pass number ≥ 3, present options before proceeding:

Pass [N] exists ([previous lens] lens). Per skill, 3 passes provide solid coverage.

Options:
1. Pass [N+1] Enrichment ([next lens] lens) — full independent discovery + merge
2. Reassessment — fresh metrics + delta comparison
3. Quick Health Check — verify existing findings still hold

Which approach?

Quick Health Check

Fastest mode. No new discovery — verification only.

1. Refresh Phase 1 metrics
2. Compare against REPORT_FILE metrics — note any significant changes
3. For each existing finding, verify against current codebase state
4. Mark findings as: ✓ verified, ✗ stale, ~ adjusted
5. Update header date and metrics
6. Do NOT explore for new findings

---

Phase 1: Metrics Collection

Quantitative backbone of the assessment. Language-agnostic.

1.1 Language Detection

Scan for manifest files to determine primary language(s):

Multi-language projects: collect metrics per language, report the primary language first.

1.2 Repository Overview

Collect per language (prefer cloc, scc, or tokei when available; fall back to wc -l):

• Production code: LOC by language (exclude tests, vendored, generated)
• Test code: LOC across test files
• Test-to-production ratio: test LOC / production LOC
• Test count: number of test functions/cases
• Documentation: LOC across docs/specs/README files
• Dependencies: direct count from manifest files

Language-specific collection hints:

These are approximations for order-of-magnitude assessment, not precision tooling.

1.3 File Size Distribution

Identify files exceeding thresholds. List top 20 largest files:

# Go
find . -name "*.go" ! -name "*_test.go" ! -path "*/vendor/*" -exec wc -l {} + | sort -rn | head -20

# Python
find . -name "*.py" ! -path "*/__pycache__/*" ! -path "*/venv/*" ! -path "*/.venv/*" -exec wc -l {} + | sort -rn | head -20

# TypeScript/JavaScript
find . \( -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.jsx" \) ! -path "*/node_modules/*" -print0 | xargs -0 wc -l | sort -rn | head -20

# Rust
find . -name "*.rs" ! -path "*/target/*" -exec wc -l {} + | sort -rn | head -20

# Or use cloc/scc/tokei if available — they handle exclusions automatically

• Flag files >500 LOC as potential god classes/scripts
• Flag files >300 LOC as candidates for investigation

1.4 Dependency Assessment

• Count direct vs transitive dependencies (where tooling supports it)
• Note dependency minimalism or bloat relative to ecosystem norms
• Check for known problematic patterns: vendored copies of actively-maintained deps, pinned ancient versions

1.5 CI/CD Assessment

• Check for CI config: .github/workflows/, .gitlab-ci.yml, Jenkinsfile, Makefile, etc.
• Check for pre-commit: .pre-commit-config.yaml
• Note what CI covers: lint, test, build, coverage, deploy
• Check for coverage enforcement (threshold gates, not just reporting)

1.6 Code Hygiene Scan

Scan for patterns that indicate quality discipline or gaps:

• Magic literals: Search for hardcoded string values used in control flow, event dispatch, identity comparison, or configuration. Language-specific patterns:

  Language	Scan Approach
  Go	rg -n '"[a-z_]*"' -g '*.go' -g '!*_test.go' filtered to control flow contexts
  Python	rg -n "['\"]\w+['\"]" -g '*.py' in if/match/dispatch contexts
  TS/JS	rg -n "['\"]\w+['\"]" -g '*.ts' in switch/if/event contexts

  Not every string literal is a magic value. Focus on:

  • Strings used in dispatch (switch/if chains, event names, status checks)
  • Strings used as identity (agent IDs, role names, service names)
  • Strings that appear in multiple files (cross-module coupling via literal)
  • Strings that shadow typed constants (the type exists but literals bypass it)

  Provenance classification — for each category of magic literal found, classify:

  Category	Example	Fix
  System constant	Event name, error code	Extract to typed constant
  Configuration value	Default port, timeout	Extract to config with default
  User-supplied identity	Agent ID, workspace name	Resolve from runtime state — a constant doesn't fix this

  The third category is the most severe: a hardcoded value that should be dynamic means the system silently assumes a specific runtime configuration. A const only consolidates the assumption; it doesn't fix it.

• Suppression markers: Count nolint, noqa, @ts-ignore, # type: ignore, eslint-disable

• Panic/exit calls: panic(), os.Exit(), process.exit(), sys.exit() in non-main code

• Untyped escape hatches: interface{}, any, Any, object in production code

• TODO/FIXME/HACK: Count and assess whether tracked or abandoned

1.7 Metrics Dashboard

Assemble findings into the dashboard format from references/report-format.md.

---

Phase 2: Subsystem Analysis

Qualitative assessment of each component.

2.1 Subsystem Identification

Walk the project structure. Identify natural subsystem boundaries:

• Top-level directories with distinct purposes
• Package/module boundaries
• Layers (domain, application, infrastructure, presentation) if identifiable

In Pairing mode: confirm identified subsystems before proceeding.

2.2 Rating Framework

Each subsystem gets a 1–5 star rating:

Rating dimensions (weight equally unless context justifies otherwise):

• Code organization: Cohesion, responsibility separation, file sizes
• Test coverage: Quality and depth of testing for this subsystem
• API clarity: Are interfaces and contracts clear?
• Error handling: How are failures managed?
• Complexity management: Is complexity proportional to the problem? When complexity is high, is it structural (file/function size — fixable by splitting) or design-level (wrong abstraction, boolean-flag dispatch, imperative ceremony — requires pattern change)? Rate lower when complexity has a design root cause, even if LOC is acceptable.

2.3 Analysis Template

For each subsystem:

### [Subsystem Name] (`path/`) ★★★★☆

**Strengths:**
- [Specific strength with evidence]

**Concerns:**
- [Specific concern with evidence — file names, LOC counts, concrete observations]

Discipline: Every strength and concern must cite evidence. "Well-tested" is not a strength — "2.5:1 test-to-production ratio with table-driven subtests" is. "Large file" is not a concern — "handlers.go at 918 LOC mixing 30+ handler functions" is.

2.4 Cross-Cutting Sections

After subsystem analysis, assess these quality dimensions that span subsystems. Include each section only when there is substantive content — an empty section is worse than an absent one.

Testing & Quality Infrastructure:

• Test framework and patterns (stdlib vs third-party, table-driven, fixtures, etc.)
• Coverage approach (reporting, enforcement, thresholds)
• Test quality enforcement (parallel tests, race detection, sleep guards, test helper isolation)
• Integration/E2E test presence and coverage

Pre-Commit & CI Pipeline:

• Hook coverage by category (lint, format, type-check, security, file hygiene)
• CI stages and platforms
• Enforcement gaps (what runs but doesn't block, what doesn't run at all)

Documentation & Specifications:

• Doc volume and coverage
• Spec depth (if specs/ exists)
• Staleness risk (specs referencing outdated implementation details)
• Onboarding path clarity

---

Phase 3: Synthesis

Aggregate findings into overall assessment.

3.1 Executive Summary

One paragraph: what the project is and its overall engineering quality.

Key Strengths (3–5 bullet points): The most impactful positive patterns. Synthesize — don't enumerate. "Clean architecture" is not a strength; "Strict layer separation with dependencies pointing inward — no infrastructure types leak into domain" is.

Areas for Improvement (3–5 bullet points): The most impactful concerns. Same evidence discipline.

3.2 Overall Grade

Grading discipline:

• Grade must be justified with specific reference to subsystem ratings and metrics
• State the deduction from the next-higher grade explicitly (e.g., "The deduction from A to A- is for file-level concentration in the MCP handlers and state model")
• Calibrate to ecosystem norms (see Reference: Language Ecosystem Norms)

---

Phase 4: Recommendations

Prioritized refactoring roadmap.

4.1 Priority Framework

4.2 Recommendation Template

For each recommendation:

#### N.M [Title]
- **What**: [Specific files/components to change and how]
- **Risk**: [Low / Medium / High] — [rationale]
- **Impact**: [What improves and why it matters]
- **Depends on**: [Other recommendations, if any]

Every recommendation must trace to a finding in Phase 2 or Phase 3. No generic "best practices" without project-specific justification.

4.3 Recommendation Anti-Patterns

• Do not recommend what the project already does well
• Do not recommend architectural rewrites when structural cleanup suffices
• Do not recommend without stating the concrete problem it addresses
• Do not recommend file splits or method extraction as the remedy for every complexity concern. Ask "why is this complex?" first — if the root cause is a design issue (boolean-flag dispatch, imperative ceremony, missing polymorphism), recommend the design-level fix. Extraction addresses structural complexity; it does not fix design complexity. If you find yourself recommending only structural remedies, you are likely missing design-level concerns.
• Sequence matters: P1 should be achievable independently; P2 may depend on P1

---

Persistence of Findings

ISSUES_FILE = specs/architecture/architectural-issues.md

Significant findings (subsystem concerns rated ★★☆☆☆ or below, P1 recommendations, cross-cutting concerns) should be persisted to ISSUES_FILE for long-term tracking.

Persistence format:

### [Issue Title]

**Skill:** code-quality-assessment
**Category:** [Subsystem concern / Cross-cutting / RECOMMENDATION]

**Issue:** [Description]

**Implication:** [Why it matters]

**Direction:** [Suggested approach, if any]

What to persist:

• Subsystem concerns with ★★☆☆☆ or below
• All P1 recommendations
• Cross-cutting concerns with systemic impact

What NOT to persist:

• Low-priority style issues
• Findings already in ISSUES_FILE (check before adding)
• Transient issues resolved in the same session

Scope Constraints

This skill assesses the whole repository, not individual diffs. Scope constraints apply to persistence (what gets written to ISSUES_FILE), not to analysis (what gets examined).

§BRAND_NAME_TITLE§ mode (multi-agent):

• Full repo assessment is the default — the skill exists for whole-codebase evaluation
• When invoked during a review task (not a standalone assessment), scope findings to what's relevant to the review context
• Persist only findings not already in ISSUES_FILE

Pairing mode:

• Do not re-raise issues already documented in ISSUES_FILE unless materially changed
• If changes worsen a documented issue, update the existing entry rather than duplicating

Mode-Specific Confirmation

Pairing mode: Before saving findings to ISSUES_FILE:

Found [N] quality issues worth persisting:
1. [Issue title] — [one-line summary]
2. ...

Save to specs/architecture/architectural-issues.md? (y/n/select specific)

Wait for user confirmation.

§BRAND_NAME_TITLE§ mode: Save automatically after assessment completion.

---

Integration

---

Reference: Metrics Calibration

Healthy ranges for calibrating assessments. These are norms, not targets.

---

Reference: Language Ecosystem Norms

Calibration varies by ecosystem. Anchoring to wrong norms produces misleading grades.

A Go project with 50 dependencies is notable; a TypeScript project with 50 is unremarkable. Grade relative to ecosystem.