Enhance Code Quality

Overview

Score a project 0-10, identify issues by severity, walk the user through fixes one-by-one, track decisions in the project instructions file so declined items are never re-raised.

Project instructions file depends on your CLI tool: Claude Code → CLAUDE.md | Codex → AGENTS.md | Kilo Code / Windsurf → equivalent config file. This skill uses "CLAUDE.md" as shorthand — substitute the correct filename for your environment.

Core principle: Respect prior decisions. Check before suggesting. Ask before changing.

Workflow

1. Read CLAUDE.md / AGENTS.md → collect accepted items
2. Run project tools → collect objective data
3. Score 0-10 with rubric
4. Filter out accepted items
5. Present Issue N
   ├── yes → 6a. Implement fix ──┐
   └── no  → 6b. Save decline ──┤
                                  ▼
                           More issues?
                           ├── yes → back to 5
                           └── no  → 7. Re-score

Step 1: Read Project Instructions File First

Before any analysis, read the entire project instructions file (CLAUDE.md / AGENTS.md / equivalent).

If no project instructions file exists: Note it and proceed to Step 2 with an empty accepted-items list. After scoring, recommend creating one as a MEDIUM issue if the project would benefit from it.

Collect deliberately accepted items from all of these sources:

• •The # Code Quality section (explicit accepted items list)
• •Any phrase like "by design", "intentional", "deliberately", "do not move/change"
• •Architecture decisions with documented rationale (e.g., "This design is intentional")
• •Dependency decisions (e.g., "Do not move X to optional-dependencies")
• •Test scope decisions (e.g., "minimal test coverage by design")

Read the entire file, not just one section. Intentional decisions are often documented inline near the relevant architecture description, not only in the "Code Quality" section.

These items are OFF-LIMITS. Do not suggest changes to deliberately accepted items. If you would have flagged something but it's documented as intentional, skip it silently.

Step 2: Run Project Quality Tools

Before manual scoring, run whatever quality tooling the project already has. Check for:

• •Makefile targets: make test, make lint, or similar
• •Project instructions file (CLAUDE.md / AGENTS.md) for test/lint commands. If not present, create it.
• •Common tools: ruff check, pyright, shellcheck, eslint, pytest, etc.
• •CI config (.github/workflows/) for the project's own quality gates

Record tool output (pass/fail, coverage %, lint warnings). Use this objective data to inform Step 3 scoring.

Step 3: Score With Rubric

Use this rubric to score the project. Each dimension is 0-10, final score is the weighted average.

Type Safety by language:

Scoring anchors (all dimensions):

Present the scorecard as a table with per-dimension scores and the weighted total.

Step 4: Filter Deliberately Accepted Items

Cross-reference your findings against all deliberately accepted items collected in Step 1 (from the "Code Quality" section AND from inline "by design" documentation throughout the project instructions file). Remove any issue that matches.

If unsure whether something is deliberately accepted: include it but note "This may be intentional per the project instructions — please confirm."

Step 5: Format and Present One-by-One

Every finding MUST use this exact format:

## Issue N: [Short Title]
**Severity**: SEVERE | MEDIUM | MINOR
**Affected files**: [list of files]
**Description**: [what's wrong]
**Suggested fix**: [specific actionable fix instructions]

Severity guidelines:

• •SEVERE: Security issues, data loss risks, critical bugs, architectural violations
• •MEDIUM: Performance issues, code quality problems, missing tests, unclear code, documentation gaps
• •MINOR: Pure style issues (formatting, naming conventions that don't affect readability)

Every issue MUST have a specific, actionable suggested fix. Not "improve this" — actual instructions.

Number issues sequentially. Present in severity order: SEVERE first, then MEDIUM, then MINOR.

Do NOT dump all issues at once. Present ONE issue at a time. After presenting, ask:

"Do you want to implement this fix? Or skip it? If skipping, what's the reason?"

Wait for the user's response before presenting the next issue.

Step 6a: Implement Accepted Fixes

Implement the change, verify it works (run relevant tests/lints), show the user what changed, move to next issue.

Step 6b: Save Declined Items to Project Instructions File

Mandatory for every decline. Append to # Code Quality section in CLAUDE.md / AGENTS.md:

Deliberately accepted items — do not flag in future reviews:

- **[Short Title]**: [User's reason]. [Brief description so future reviewers understand.]

If the section exists, append. Do not duplicate entries. If the section does not exist, create it at the end of the project instructions file. If no project instructions file exists, create one (CLAUDE.md / AGENTS.md) with the # Code Quality section.

Step 7: Re-score

After all issues processed, re-run the rubric. Present before/after scorecard.

Common Mistakes