/pair-capability-analyze-code-quality — Code Quality Analysis

Evaluate code quality using objective metrics from code-metrics.md. Produces a quality report with complexity, size, coverage, duplication, and maintainability scores. Includes actionable recommendations for improvement. Output-only: this skill inspects code and runs coverage but writes no files — it never mutates adoption, code, or the PM tool.

Arguments

Argument	Required	Description
$scope	No	Limit analysis to specific metric group: complexity, size, coverage, duplication, maintainability, all (default: all)
$path	No	Limit analysis to a specific file, directory, or package. If omitted, analyzes the full codebase.

Algorithm

Step 1: Resolution Cascade

Read resolution cascade for the generic Path A/B/C mechanics — this skill uses the report-skill variant and has no override argument, so it starts directly at the idempotency check (no Path A/Argument-Override).

• Existing-state check (Path B): an existing quality report for this codebase (conversation context, CI artifacts, prior output). Staleness test: has the codebase changed since the last analysis (git diff --stat since last analysis date/commit)? No changes → confirm and exit. Changes exist → present the delta and proceed to full analysis.
• Full-analysis path (Path C): proceed to Step 2.

Step 2: Read Quality Metrics Guidelines

1. Act: Read code-metrics.md for:
   • Complexity metrics: cyclomatic complexity, cognitive complexity, nesting depth
   • Size metrics: lines of code, function length, class/module size, file size
   • Quality metrics: test coverage, code duplication, maintainability index
   • Thresholds per metric (e.g., cyclomatic complexity 1-5 = simple, 16+ = refactor needed)
2. Verify: The thresholds for every metric group in $scope are known from code-metrics.md (or the Graceful Degradation built-in defaults) before Step 3 collects metrics against them.

Step 3: Collect Metrics

For each metric group in scope, follow check → skip → act → verify.

3.1: Complexity Metrics

1. Act: Analyze code for:
   • Cyclomatic complexity per function: count decision points (if, else, switch, for, while, catch, &&, ||)
   • Cognitive complexity: weight nested conditions higher than flat ones
   • Maximum nesting depth: deepest level of nested control structures
2. Act: Classify per function:
   • Simple (1-5), Moderate (6-10), Complex (11-15), Very Complex (16+)
3. Verify: Complexity metrics collected.

3.2: Size Metrics

1. Act: Measure:
   • Lines of code per file (excluding blank lines and comments)
   • Function length: lines per function (threshold: > 50 lines = warning)
   • File size: lines per file (threshold: > 300 lines = warning)
   • Module count: total modules/files in the project or scope
2. Verify: Size metrics collected.

3.3: Test Coverage

1. Act: Run the test suite with coverage reporting (e.g., vitest --coverage, jest --coverage).
2. Act: Collect coverage metrics:
   • Line coverage: % of lines executed by tests (target: 70-90%)
   • Function coverage: % of functions called by tests (target: 80-90%)
   • Branch coverage: % of branches taken by tests (target: 60-75%)
3. Verify: Coverage metrics collected. If coverage tool not available, skip with warning.

3.4: Code Duplication

1. Act: Scan for duplicated code blocks:
   • Exact duplicates (copy-paste)
   • Near-duplicates (structural similarity > 80%)
   • Duplication ratio: duplicated lines / total lines
2. Act: Classify: Low (< 3%), Moderate (3-5%), High (> 5%)
3. Verify: Duplication metrics collected.

3.5: Maintainability Index

1. Act: Calculate composite maintainability score (0-100) based on:
   • Average complexity (lower is better)
   • Average function length (shorter is better)
   • Test coverage (higher is better)
   • Duplication ratio (lower is better)
2. Act: Classify:
   • Excellent (80-100): Well-maintained, easy to modify
   • Good (60-79): Generally maintainable, minor improvements possible
   • Fair (40-59): Maintenance challenges, targeted refactoring recommended
   • Poor (0-39): Significant maintenance burden, systematic improvement needed
3. Verify: Maintainability index calculated.

Step 4: Generate Report

1. Act: Compile all metrics into a quality report.
2. Act: Identify hotspots — files or functions that exceed multiple thresholds.
3. Act: Generate recommendations ordered by impact:
   • Each recommendation references the metric, current value, threshold, and suggested action.

Step 5: Present Report

1. Act: Present the report to the developer with recommendations.
2. Verify: Report presented. No side effects — this step is purely informational output, not a decision point, so there is nothing to confirm.

Output Format

Follows the Report Shape.

CODE QUALITY REPORT:
├── Scope:           [$scope — $path or full codebase]
├── Complexity:      [avg cyclomatic: N | N functions > 10 | max nesting: N]
├── Size:            [N files | avg lines: N | N files > 300 lines | N functions > 50 lines]
├── Test Coverage:   [line: N% | function: N% | branch: N% | SKIPPED]
├── Duplication:     [ratio: N% — Low/Moderate/High]
├── Maintainability: [score: N/100 — Excellent/Good/Fair/Poor]
└── Hotspots:        [N files flagged]

HOTSPOTS:
1. [file] — [metric: value, metric: value] — [recommendation]
2. ...

RECOMMENDATIONS:
1. [priority] [metric] — [current] → [target]: [action]
2. ...

RESULT: [Quality score: N/100 | Analyzed | Confirmed existing]

Composition Interface

When composed by /pair-process-review:

• Input: /pair-process-review may invoke /pair-capability-analyze-code-quality during the technical review phase.
• Output: Returns the quality report. /pair-process-review incorporates metrics and hotspots into review findings.
  • Poor maintainability or high complexity may inform review recommendations.
  • Metrics are informational — the review always proceeds regardless of score.

When invoked independently:

• Full interactive flow. Developer receives the report and decides on improvement actions.

Graceful Degradation

See graceful degradation (guideline missing → fall back to built-in thresholds: cyclomatic > 10, function > 50 lines, file > 300 lines, coverage > 70%) for the standard scenarios. Additional cases:

• If coverage tools are not available, skip test coverage metrics and note: "Coverage: SKIPPED — no coverage tool detected."
• If duplication detection is not feasible (no tool), use heuristic scanning for obvious copy-paste patterns.
• If the codebase is too large for full analysis, limit to changed files (PR scope) and note: "Partial analysis — limited to changed files."

Notes

• This skill is read-only / output-only — it only inspects code and runs coverage (via existing test commands); files, adoption, and the PM tool stay untouched. A finding worth tracking is promoted deliberately to the backlog via /pair-capability-write-issue — always a manual, selective act.
• Idempotent — see idempotency convention. This skill's check: staleness of the existing report (Step 1) — unchanged codebase confirms it, changed codebase re-analyzes.
• Metrics are health indicators, not absolute quality measures. Context matters: business logic naturally has higher complexity, and metric targets should align with team capabilities.
• Quality analysis is most valuable as a trend — individual snapshots matter less than improvement direction over time.
• The maintainability index is a composite heuristic — it provides a single number for quick analysis but the component metrics offer more actionable insights.