Code Quality Loop
warning
This page is a retained loop design. Its named template and prompt are not
currently tracked under .agents/tasks; restore and review those artifacts
before attempting to run it.
Overview
The code quality loop runs scoped static analysis, triages findings by severity, applies safe fixes, and verifies no regressions were introduced. It never changes observable behavior -- all fixes are mechanical (type errors, unused imports, dead code).
Template: prd-code-quality.template.json
Prompt: PROMPT_code-quality.md
Stories: 6 (Q00-Q05)
Slash command: /code-quality-loop-bootstrap [scope]
Story Breakdown
| ID | Title | Depends On | Output |
|---|---|---|---|
| Q00 | Preflight: load and lock effective scope | -- | .ralph/scope-effective.md |
| Q01 | Baseline: run scoped quality checks | Q00 | .ralph/quality-findings.md |
| Q02 | Triage: rank and plan remediation | Q01 | .ralph/quality-plan.md |
| Q03 | Remediation: apply critical/high fixes | Q02 | Modified source files |
| Q04 | Verification: rerun checks and tests | Q03 | .ralph/quality-report.md |
| Q05 | Handoff: publish quality report | Q04 | .ralph/quality-report.md (final) |
Flow
What the Loop Fixes
| Safe to Fix | Deferred to Human |
|---|---|
| TypeScript type errors in scope | Function signature changes |
| Unused imports and variables | Complex cascading type errors |
| Unreachable / dead code | Changes that affect public behavior |
| Missing type annotations on exports | Architectural refactors |
| ESLint violations (if configured) | Performance improvements |
Finding Severity
| Severity | Examples |
|---|---|
| Critical | TypeScript compile error, broken import, undefined reference |
| High | Unhandled promise, missing null check on user input, deprecated API |
| Medium | Unused variables, unreachable code, console.log in production |
| Low | Style preferences, naming conventions, minor readability |
Q03 addresses critical and high findings. Medium and low are addressed if capacity allows.
Quality Gates
- Read
.ralph/intake/current-guidelines.jsonat the start of every story - Never modify files outside
scope.includeexcept tracking artifacts - Preserve public behavior unless constraints explicitly allow changes
- Do not apply fixes before findings are captured in
quality-findings.md - Do not mark remediation complete without post-fix validation evidence
- For touched files, run the narrowest available lint/test checks first
- Document before/after counts by severity in
quality-report.md
Artifacts
| File | Written By | Purpose |
|---|---|---|
.ralph/scope-effective.md | Q00 | Expanded include/exclude paths with hard guards |
.ralph/quality-findings.md | Q01 | Normalized findings (severity, rule, file, fix hint) |
.ralph/quality-plan.md | Q02 | Ordered remediation batches with deferred items |
.ralph/quality-report.md | Q04-Q05 | Before/after counts, residual risk, next steps |
Run Command
# Bootstrap with a specific scope:
/code-quality-loop-bootstrap src/auth/**
# Then run Ralph:
PROMPT_BUILD=.agents/ralph/PROMPT_code-quality.md \
PRD_PATH=.agents/tasks/prd-active.json \
bash .agents/ralph/loop.sh