Code Qualities Assessment

Evaluate code maintainability using 5 timeless design qualities with quantifiable scoring rubrics.

Triggers

• assess code quality
• evaluate maintainability
• check code qualities
• testability review
• run quality assessment

Quick Start

# Assess a single file
python3 scripts/assess.py --target src/services/auth.py

# Assess changed files from the PR base (CI mode)
python3 scripts/assess.py --target . --changed-only --base origin/main --format json

# Full module assessment with HTML report
python3 scripts/assess.py --target src/services/ --format html --output quality-report.html

Scripts

Use --changed-only for diff-scoped checks and --format json for automation.

The 5 Code Qualities

When to Use

Use this skill when:

• Reviewing code quality before merge
• Identifying refactoring priorities
• Establishing quality baselines
• Teaching code design principles
• Tracking quality trends over time
• Enforcing quality gates in CI

Use [analyze](../analyze/SKILL.md) instead when:

• Performing broad codebase investigation
• Security assessment is the focus
• Architecture review is needed

Process

The skill runs automated assessment via scripts/assess.py:

1. Symbol Extraction

- Detect language - Use Serena (if available) - Extract classes/methods

1. Quality Scoring

- Run 5 quality assessments - Apply context rules (test vs prod) - Aggregate symbol -> file -> module

1. Comparison (if historical data)

- Load previous scores - Identify regressions/improvements

1. Report Generation

- Format: markdown, JSON, or HTML - Include remediation guidance - Link to refactoring patterns

1. Gate Enforcement (CI mode)

- Regression mode compares each changed file against its base revision - Absolute mode compares every assessed file against configured thresholds - Exit code: 0=pass, 10=regressed, 11=below thresholds

Command Reference

Basic Usage

python3 scripts/assess.py --target <path> [options]

Parameters

Gate Modes

The gate answers one of two questions. Pick the one your caller actually asks.

--gate-mode regression requires both --changed-only and --base, and exits 1 without them. It never silently falls back to absolute thresholds: that fallback is exactly how a gate advertised as regression-only ends up blocking on inherited debt.

In regression mode, each changed file is scored twice, once at the merge base of --base and HEAD through git show and once at head, using the same scoring code. The merge base, not the tip of --base: file selection is git diff --name-status -M -z base...HEAD, which git resolves from the merge base. Rename records retain both paths, so the head file is scored against the old path's base blob instead of being misclassified as new. A missing path is new only when the diff marks it added; a failed tree or blob read is an error. Reading content at the tip would score the branch against commits that landed on the base branch after the fork. Qualities are compared independently and only where both revisions scored them (confidence above 0.0), so a file whose scored-quality set changed is never compared against a different set. Aggregate averages are never compared. A quality that goes from scored to unscored counts as evidence loss and fails, unless the file is now a generated artifact. A quality that goes from unscored to scored is reported with no delta. A file absent at the merge base is new, has no delta, and is gated absolutely. A base file with no scored qualities also provides no comparison, so the head is gated absolutely. This covers extension-changing renames such as an unscored legacy.txt becoming scored renamed.py. A file the assessor cannot decode as UTF-8 at the merge base (a binary, a latin-1 source) scores nothing there, so the head is gated absolutely rather than passing on missing evidence.

Every score is size-derived, so adding one small function moves a quality by a few tenths with nothing wrong. --regression-tolerance defaults to 0.5 for that reason: measured, one 2-line function added to a 5-function module drops cohesion 8.7 to 8.3, while a real degradation moves whole points. Pass 0.0 to gate on any drop at all.

Growth costs more than the tolerance absorbs, and cohesion is where it shows. The score is 10 - LOC/120 - 0.3 * (definitions - 1) at confidence 0.4, so a file that gains three functions and 100 lines loses about 1.7 points whether or not anything got worse. A test module gaining tests hits this every time. Read the named delta before acting on an exit 10: this heuristic cannot tell growth from decay, and a file that grew for a good reason is the common case.

The JSON report carries gate_mode and a comparisons array with per-quality base, head, delta, and status.

Exit Codes

Configuration

Create .qualityrc.json to customize thresholds:

{
  "thresholds": {
    "cohesion": { "min": 7 },
    "coupling": { "min": 7 },
    "encapsulation": { "min": 7 },
    "testability": { "min": 6 },
    "nonRedundancy": { "min": 8 }
  },
  "context": {
    "test": {
      "testability": { "min": 3 }
    }
  },
  "ignore": [
    "**/generated/**",
    "**/*.pb.py",
    "**/migrations/**"
  ]
}

Anti-Patterns

Verification

After running assessment, run the bundled validator and require exit 0:

python3 .claude/skills/code-qualities-assessment/scripts/assess.py --target "$TARGET_PATH"
echo "exit=$?"   # must be 0; 10 = regressed, 11 = thresholds not met, 1 = script error

• assess.py exited 0 (10 = regressed; 11 = thresholds not met; 1 = script error; none is a pass)
• All 5 qualities scored for each symbol
• Scores are 1-10 (not null or out of range)
• Remediation links provided for low scores
• Report format is valid (markdown/JSON/HTML)
• Historical data saved to .quality-cache/

<details> <summary><strong>Deep Dive: Scoring Rubrics</strong></summary>

Cohesion

How strongly related are responsibilities within a boundary?

High cohesion = focused, understandable code. Low cohesion = "god objects" doing too much.

Coupling

How dependent is this code on other code?

Loose coupling = independent evolution, easy testing. Tight coupling = fragile, hard to test.

Encapsulation

How well are implementation details hidden?

Good encapsulation = freedom to change internals. Poor encapsulation = brittle API.

Testability

How easily can behavior be verified in isolation?

Testable code = fast feedback, confidence to refactor. Untestable code = fear of change.

Non-Redundancy

How unique is each piece of knowledge?

DRY code = fix once, single source of truth. Duplication = fix N times, maintenance burden.

</details>

<details> <summary><strong>Deep Dive: Examples</strong></summary>

Example 1: Single File Assessment

python3 scripts/assess.py --target src/models/user.py

Output:

# Code Quality Assessment: src/models/user.py

## Summary
- **Cohesion**: 8/10
- **Coupling**: 4/10
- **Encapsulation**: 9/10
- **Testability**: 7/10
- **Non-Redundancy**: 9/10

## Issues Found

### Coupling: 4/10 (Warning)
**Problem**: Direct instantiation of DatabaseConnection in constructor

**Impact**: Hard to test, tightly coupled to database layer

**Remediation**: Use dependency injection
- See: [Refactoring Patterns](references/refactoring-patterns.md)
- Related ADR: ADR-023 (Dependency Management)

Example Fix:

# Before
class User:
    def __init__(self):
        self.db = DatabaseConnection()  # Hard-coded dependency

# After
class User:
    def __init__(self, db: DatabaseInterface):
        self.db = db  # Injected dependency

Example 2: CI Integration

# In CI pipeline. --changed-only with --base selects regression mode.
python3 scripts/assess.py --target . --changed-only --base origin/main \
  --format json --output quality.json

# Exit code 0  = nothing this change touched got worse, pass
# Exit code 10 = a comparable quality regressed, fail PR
# Exit code 11 = a file added by this change is below thresholds, fail PR

Example 3: Full Codebase Report

python3 scripts/assess.py --target src/ --format html --output reports/quality.html

Opens dashboard showing:

• Quality trends over time
• Hot spots (lowest scoring files)
• Improvement opportunities
• Top refactoring priorities

</details>

<details> <summary><strong>Deep Dive: Integration with Other Skills</strong></summary>

With planner

# Identify refactoring targets
python3 scripts/assess.py --target src/ --format json | \
  jq '.files | sort_by(.overall) | .[0:5]' > low-quality-files.json

# Feed to planner
planner --input low-quality-files.json --goal "Refactor lowest quality files"

With adr-review

When reviewing ADRs, include quality impact:

# Before implementing ADR
python3 scripts/assess.py --target affected-files.txt > baseline.md

# After implementing ADR
python3 scripts/assess.py --target affected-files.txt > post-implementation.md

# Compare
diff baseline.md post-implementation.md

With analyze

Combine broad analysis with focused quality metrics:

# First: broad exploration
analyze --target src/

# Then: quality deep dive on problem areas
python3 scripts/assess.py --target src/services/auth.py

</details>

<details> <summary><strong>Deep Dive: Scoring References</strong></summary>

For detailed methodology and examples:

• [Calibration Examples](references/calibration-examples.md)
• [Refactoring Patterns](references/refactoring-patterns.md)
• [Dotnet Performance Patterns](references/dotnet-performance-patterns.md)

</details>

References

Language Support

Serena integration improves accuracy when available.

Design Philosophy

This skill embodies "sergeant methods directing privates":

• Sergeant (assess.py): Orchestrates workflow, delegates to specialists
• **Privates (score_*.py)**: Focus on one quality each, report back

Each quality scorer is cohesive (single responsibility), loosely coupled (independent), and testable (pure calculation).

Timelessness: 9/10

These 5 qualities are computer science fundamentals:

• Cohesion and coupling: 1970s (Parnas, Stevens)
• Encapsulation: Core OOP principle (1960s)
• Testability: TDD movement (1990s-2000s)
• DRY: Pragmatic Programmer (1999)

Language-agnostic design ensures longevity across technology shifts.