tomevault-io 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 Qualitysection (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:
Makefiletargets: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 |
Converted and distributed by TomeVault — claim your Tome and manage your conversions.