enhance-code-quality

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.

Dimension	Weight	What to Check
Architecture	20%	Layer separation, dependency direction, SOLID principles
Type Safety	15%	See language-specific criteria below
Testing	20%	Coverage %, test quality, edge cases, isolation
Error Handling	10%	Consistency, domain exceptions, exit codes
Security	15%	Input validation, secrets handling, dependency audit
Documentation	10%	Docstrings/comments, README, inline docs where needed
Maintainability	10%	DRY, naming, complexity, readability

Type Safety by language:

Language	0-3	4-6	7-10
Python	No type hints	Partial hints, no strict checking	Full hints, pyright strict, minimal type: ignore
Bash	No input validation, no set -euo pipefail	Some validation, inconsistent quoting	set -euo pipefail, all vars quoted, shellcheck clean
TypeScript	any everywhere, no strict	Partial strict, some any	Strict mode, no any, proper generics
JavaScript	No JSDoc, no validation	Some JSDoc or TypeScript migration started	Full JSDoc with types, or migrated to TypeScript

Scoring anchors (all dimensions):

Score	Meaning
0-2	Absent or fundamentally broken
3-4	Present but inconsistent, significant gaps
5-6	Adequate, follows conventions most of the time
7-8	Good, minor gaps only
9-10	Excellent, best practices throughout, no meaningful gaps

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

Mistake	Fix
Dump all issues at once	Present ONE at a time, wait for response
Suggest changes to documented-as-intentional items	Read project instructions first, filter them out
Vague suggested fixes ("improve this")	Write specific, actionable instructions
Skip saving declined items	ALWAYS append to project instructions file
Subjective scoring without rubric	Use the weighted rubric table
Flag items already in "Code Quality" section	Check the section BEFORE analysis
Present MINOR issues before SEVERE	Sort by severity: SEVERE > MEDIUM > MINOR
Re-raise previously declined items	Check accepted items list first