[writes] Fix all codebase quality issues iteratively. Use when you want to clean up technical debt, polish a codebase before release, or fix all convention violations. Dispatches review agents, fixes findings, commits per iteration, loops until clean.
See shared/skill-contract.md for the standard exit-code table.
Before any action, verify:
git rev-parse --show-toplevel 2>/dev/null. If fails: report "Not a git repository. Navigate to a project directory." and STOP..claude/forge.local.md exists. If not: report "Forge not initialized. Run /forge-init first." and STOP.shared/mcp-detection.md detection table. Mark unavailable MCPs as degraded.You are an autonomous codebase health improvement loop. You dispatch forge's own review agents to find issues, fix aggressively, re-dispatch to verify, and iterate until clean. Every iteration ends with a commit.
Core principle: The same forge review agents that find issues also verify fixes. No separate "investigation" vs "review" — one set of agents, used twice per iteration.
Parse $ARGUMENTS:
--changed: Only files changed in current branch vs main/master.--files <pattern>: Specific files or directories.--focus <domain>: Limit to: architecture, security, performance, quality, tests, docs, frontend, or all (default).--max-iterations <N>: Override iteration cap (default: 5).PROJECT_ROOT=$(git rev-parse --show-toplevel)
# Get files to investigate
FILES=$(git diff --name-only $(git merge-base origin/master HEAD 2>/dev/null || echo HEAD~10)..HEAD 2>/dev/null)
[ -z "$FILES" ] && FILES=$(git ls-files --cached --exclude-standard | grep -E '\.(kt|kts|java|ts|tsx|js|jsx|py|go|rs|c|h|cs|cpp|swift|rb|php|dart|ex|scala|vue|svelte|html|css|scss)$')
Run the check engine for a fast baseline scan (Layer 1 + Layer 2):
echo "$FILES" | while read -r f; do
"${CLAUDE_PLUGIN_ROOT}/shared/checks/engine.sh" --review --project-root "$PROJECT_ROOT" --files-changed "$PROJECT_ROOT/$f" 2>/dev/null
done
Record baseline score. Save ITERATION_BASE_SHA=$(git rev-parse HEAD).
Dispatch forge's own review agents to investigate the scoped files. Select agents based on --focus and file types:
| Agent | Dispatched when |
|---|---|
forge:fg-410-code-reviewer | Always (unless --focus excludes) |
forge:fg-411-security-reviewer | Always |
forge:fg-412-architecture-reviewer | Always (unless --focus excludes) |
forge:fg-418-docs-consistency-reviewer | Always (or --focus docs) |
forge:fg-413-frontend-reviewer | Frontend files. Modes: full (default), conventions-only, a11y-only, performance-only. |
forge:fg-416-performance-reviewer | Backend files present |
forge:fg-417-dependency-reviewer | Dependency files or manifests changed/present |
forge:fg-419-infra-deploy-reviewer | Infra files present (Dockerfile, helm, k8s manifests) |
When dispatching fg-413-frontend-reviewer, the mode is selected based on --focus:
--focus value | fg-413 mode | Sections executed |
|---|---|---|
(none) or all | full | A+B+C+D+E (conventions, design, a11y, performance, cross-browser) |
frontend | full | A+B+C+D+E |
quality | conventions-only | A+B (conventions, design) |
a11y | a11y-only | C (accessibility including dynamic testing) |
performance | performance-only | D (bundle size, rendering, resource loading) |
Dispatch applicable agents in parallel (max 3 at a time to manage context). Each receives:
.claude/forge.local.md if present)Agents return findings in standard format: file:line | CATEGORY | SEVERITY | message | fix_hint
Compile ALL findings from all agents. Deduplicate by (file, line, category) — keep highest severity. Score: max(0, 100 - 20*CRITICAL - 5*WARNING - 2*INFO).
Prioritize:
For each finding (highest severity first):
After all fixes are applied and tests pass, re-dispatch the SAME review agents against the changed files:
git diff --name-only $ITERATION_BASE_SHA..HEAD
Process findings:
Inner verification loop hard cap: 3 passes per iteration (prevents oscillation).
After verification is clean:
git add <changed files — be specific, no git add -A>
git commit -m "<type>: <concise description>"
One commit per iteration. Follow project commit conventions per shared/git-conventions.md — check for existing hooks (Husky, commitlint, etc.) and adopt the project's format.
If continuing: return to Step 3 (Investigation), but narrow scope to files affected by the previous iteration's changes. This prevents re-scanning the entire codebase.
After the loop ends, dispatch ALL forge review agents one final time against the full diff range:
FULL_BASE=$(git merge-base origin/master HEAD 2>/dev/null || git merge-base origin/main HEAD 2>/dev/null || echo $INITIAL_BASE_SHA)
FULL_HEAD=$(git rev-parse HEAD)
git diff --name-only $FULL_BASE..$FULL_HEAD
This catches cross-iteration inconsistencies. Score the result.
Report to user:
## Deep Health Complete
Iterations: {N}
Issues fixed: {M} ({critical} critical, {warning} warnings, {info} info)
Final score: {S}/100
Commits: {list of commit SHAs + messages}
### Remaining (if any)
- {issue}: {reason not fixed — out of scope / intentional design / accepted trade-off}
Save to .forge/forge-deep-health-report.md.
Respects forge-config.md parameters when available:
max_iterations — iteration cap (default: 5)pass_threshold — minimum quality score (default: 80)autonomous — if true, skip user confirmation between iterationsconvergence.oscillation_tolerance — score delta considered "no progress"/forge-codebase-healthgit log--max-iterations)| Condition | Action |
|---|---|
| Prerequisites fail | Report specific error message and STOP |
| Agent dispatch fails | Skip failed agent, continue with remaining. Log WARNING. If all agents fail, report ERROR and STOP |
| Fix introduces regression (tests fail) | Revert the specific fix, mark finding as unfixable, continue with next finding |
| Build/test command unknown | Skip verification step. Log WARNING: "No build/test commands detected." |
| Max iterations reached with issues remaining | Report remaining issues and suggest manual review |
| State corruption | This skill does not depend on state.json -- it runs independently |
/forge-codebase-health -- Read-only analysis without fixes (use to preview what deep-health would fix)/forge-review -- Review and fix only recently changed files (narrower scope)/forge-verify -- Quick build + lint + test check/forge-security-audit -- Focused security vulnerability scanning