remediate

name	remediate
description	Auto-fixes runtime issues found during visual verification (Stage 6V) using a categorized fix-verify cycle. This skill should be used when the user asks to "run runtime remediation", "fix 6V failures", "run Stage 6R", "auto-fix verification issues", "remediate runtime issues", "fix the verification report failures", or "run the remediation cycle", or when the transmute-pipeline agent reaches Stage 6R of the pipeline.
version	1.0.0

Stage 6R: Runtime Remediation

Read the Stage 6V verification report, categorize every failure by fixability, auto-fix all mechanical issues, and produce a human-review TODO list for issues requiring judgment — then re-verify to confirm fixes work. Lead a multi-agent runtime remediation project using Claude Code Agent Teams.

Read the detailed guide at ${CLAUDE_SKILL_ROOT}/references/remediate-detailed-guide.md for full fixability taxonomy, teammate prompts, safety rules, and report templates.

Prerequisites

1. Stage 6V must have produced a report: ./plancasting/_audits/visual-verification/report.md must exist. If not, run Stage 6V first.

2. Feature Scenario Matrix must exist: Verify ./plancasting/_audits/visual-verification/feature-scenario-matrix.md exists (generated by Stage 6V).

3. 6V gate decision check:

   • 6V PASS: Skip 6R entirely -- proceed to 6P or 6P-R. No failures to remediate.
   • 6V CONDITIONAL PASS with 6V-A/6V-B issues: Proceed with 6R.
   • 6V CONDITIONAL PASS with ONLY 6V-C issues: Skip 6R -- proceed to 6P or 6P-R. 6R cannot fix 6V-C.
   • 6V FAIL: STOP -- fix critical issues manually first, then re-run 6V.

4. Create output directory:

   mkdir -p ./plancasting/_audits/runtime-remediation
   

Input

• 6V Verification Report: ./plancasting/_audits/visual-verification/report.md (primary input)
• Feature Scenario Matrix: ./plancasting/_audits/visual-verification/feature-scenario-matrix.md
• Codebase: Backend and frontend directories
• Tech Stack: ./plancasting/tech-stack.md
• Project Rules: ./CLAUDE.md
• PRD: ./plancasting/prd/ (for understanding intended behavior)
• E2E Constants: ./e2e/constants.ts

Check ./plancasting/tech-stack.md for the Session Language setting. Generate all reports in that language. Code and file names remain in English.

Stack Adaptation

Adapt to your plancasting/tech-stack.md: middleware path, route whitelist mechanism, loading state pattern, i18n files, data fetching patterns, backend directory. Replace npm run with your project's package manager per CLAUDE.md.

Phase 1: Lead Analysis & Issue Triage

Complete BEFORE spawning teammates:

1. Check cycle counter (prevents infinite remediation cycles):

   • Read ./plancasting/_audits/runtime-remediation/loop-count.txt. If absent, this is run 1 — proceed.
   • If it contains 1 or 2, previous runs have completed — proceed.
   • If it contains 3, 3 runs have already completed — STOP immediately. Create ./plancasting/_audits/runtime-remediation/remaining-blockers.md and halt. Do NOT proceed to 6P or 6P-R.
   • Counter increment: Do NOT write to loop-count.txt here. The counter is incremented at the END of Phase 4 (after verification completes) to ensure it tracks completed runs, not started runs. Important: The 3-cycle counter resets only after a full 6V re-run between 6R sessions — simply re-running 6R without a 6V re-run does NOT reset it.

2. Read project context: ./CLAUDE.md, ./plancasting/tech-stack.md, ./plancasting/_audits/visual-verification/report.md

3. Parse and categorize every failure: For each 6V failure, record the reference (SC/US/FEAT/FS/NS/AS/ES/RS-NNN), description, severity, and assign to 6V-A (auto-fix), 6V-B (semi-auto), or 6V-C (human judgment).

   Quick triage rule: One-file edit, route addition, or wiring existing function -> 6V-A. Understanding multiple files or pattern-matching -> 6V-B. New business logic, architecture decisions, or trade-offs -> 6V-C.

   Early exit: If zero 6V-A and zero 6V-B (all 6V-C): generate report noting no mechanical fixes, skip to 6P/6P-R.

4. Group fixes by domain to prevent teammate conflicts:

   • Navigation & Routing: middleware, route files, layout components, Link hrefs
   • Component & UI: loading states, empty states, event handlers, i18n keys
   • Backend & Data: mutations, type mismatches, auth context
   • Ensure NO two teammates modify the same file.

5. Establish baseline:

   bun run typecheck > ./plancasting/_audits/runtime-remediation/baseline-typecheck.log 2>&1
   bun run test > ./plancasting/_audits/runtime-remediation/baseline-tests.log 2>&1
   

   Abort gate: If baseline shows failures unrelated to 6V issues, STOP — pre-existing failures must be resolved before 6R can proceed.

6. Create the remediation plan at ./plancasting/_audits/runtime-remediation/plan.md with triage summary, 6V-A/6V-B/6V-C issue tables, teammate assignments, and file->teammate mapping.

Phase 2: Spawn Remediation Teammates

Spawn up to 3 teammates based on triage. Teammates work in parallel on SEPARATE file sets.

Teammate 1: "navigation-routing-fixer"

Fixes: public routes blocked by middleware, dead links, broken hrefs, mobile nav gaps, sub-nav tab 404s, auth redirect issues. NEVER use wildcard middleware whitelists. For public route fixes, verify in a fresh unauthenticated browser session.

Teammate 2: "component-ui-fixer"

Fixes: broken button handlers, missing loading/empty states, missing i18n keys, missing imports, TypeScript runtime errors, missing confirmation dialogs. NEVER change visual design. Verify mutations exist before wiring buttons.

Teammate 3: "backend-data-fixer"

Fixes: wrong response shapes, auth context propagation, empty query results, missing error handling, subscription issues. NEVER create business logic. NEVER modify schema.

Each teammate runs bun run typecheck after EVERY fix. Each reports: fixes applied, files modified, issues escalated to 6V-C.

Phase 3: Integration & Verification

1. Merge and validate: Verify no file conflicts. Run full validation:

   bun run typecheck
   bun run lint
   bun run test
   

   If any check regresses from baseline, identify the causing fix, revert it, move to 6V-C.

2. Start the dev server: Check if running, start if needed. If it fails to start, mark fixes as "unverifiable" and proceed to report (unlike 6V/6P which ABORT, 6R proceeds because fixes are already applied to code).

3. Targeted re-verification: For each fix, use Playwright browser tools (navigate, screenshot, console check) to verify the issue is resolved. For public route fixes, use browser_close + fresh session. Quick regression sweep of ~5-10 key pages. If a fix didn't resolve the issue, revert and move to 6V-C.

   3-breakpoint verification: For UI fixes, verify at all 3 breakpoints (1440px desktop, 768px tablet, 375px mobile) to ensure responsive behavior is maintained.

   Tier-based screenshot handling: For 6V-A fixes, a single screenshot at the primary breakpoint is sufficient. For 6V-B fixes, capture before/after screenshots at all 3 breakpoints. For fixes affecting responsive layout, always verify at mobile (375px).

4. Update 6V report: Append remediation results section to ./plancasting/_audits/visual-verification/report.md. Update the ## Gate Decision section: if all 6V-A/6V-B resolved and zero 6V-C remain, change to PASS. If 6V-C remain, change to CONDITIONAL PASS (6V-C remaining).

5. Generate remediation report at ./plancasting/_audits/runtime-remediation/report.md with summary, triage results, verification status, files modified, remaining issues by severity, cycle tracking, gate decision, rules extracted, and next steps.

6. Extract verified fix patterns as rules (see CLAUDE.md 'Path-Scoped Rules'): For each verified 6V-A/6V-B fix, evaluate if the pattern is generalizable:

   • Is this a tech-stack gotcha? -> rule candidate
   • Is this a recurring pattern (same issue in 3+ routes)? -> rule candidate
   • Is this a 6V-C revealing a tech-stack limitation? -> rule candidate Route by confidence: HIGH (2+ features) -> .claude/rules/, MEDIUM -> plancasting/_rules-candidates.md. 6R rules are inherently higher confidence than 5B rules (verified working fixes).

7. Commit: Identify backend directory from plancasting/tech-stack.md. Stage specific files (avoid git add -A):

   git add src/ <backend-dir>/ plancasting/_audits/runtime-remediation/ plancasting/_audits/visual-verification/report.md .claude/rules/ plancasting/_rules-candidates.md
   git commit -m "fix: Stage 6R auto-remediation -- [n] issues resolved, [n] rules extracted"
   

8. Save commit hash:

   git rev-parse HEAD > ./plancasting/_audits/runtime-remediation/last-remediated-commit.txt
   

Phase 4: Shutdown

1. Request shutdown for all teammates.
2. Verify all modifications saved and committed.
3. Increment cycle counter: After all verification is complete, update loop-count.txt. If absent, create with 1. If exists, increment by 1. Only increment after Phase 3 verification fully completes — interrupted runs do not count.
4. Leave the dev server running if Stage 6P or 6P-R will run immediately.

Unfixable Violation Protocol

If a runtime issue requires architectural changes beyond this stage's scope:

1. Document in ./plancasting/_audits/runtime-remediation/category-c-escalations.md
2. Mark as 'REQUIRES HUMAN DECISION'
3. Include in final report under '6V-C Escalations'
4. Continue fixing remaining 6V-A/6V-B issues — do not block the cycle

Post-3-Cycles Escalation

After 3 internal fix-verify cycles within a single 6R run, if 6V-A/6V-B issues persist, remaining 6V-A/B issues auto-escalate to 6V-C:

• Update escalated issues to 6V-C (human judgment required)
• Update gate to CONDITIONAL PASS
• Proceed to 6P/6P-R without further cycle attempts
• Create remaining-blockers.md listing all unresolved issues
• Operator must: (a) manually resolve, re-run 6V, then 6R if needed, OR (b) document as known limitations and proceed to 6P
• If 6R gate is FAIL after max cycles, do NOT re-run 6R — manually fix 6V-C issues first, re-run 6V, then 6R if needed
• Outer cycle tracking: Track outer cycle count by counting 6R report files or noting cycle number in report headers

Gate Decision

• PASS: All 6V-A and 6V-B issues resolved. Remaining 6V-C issues documented with rationale.
• CONDITIONAL PASS: Some 6V-B issues remain with workarounds documented. All 6V-A issues resolved.
• FAIL: 6V-A or 6V-B issues remain unresolved without workarounds.

Next Steps

• PASS: proceed to Stage 6P or 6P-R (Visual Polish or Redesign) -> Deploy -> 7V -> 7D
• CONDITIONAL PASS: human reviews remaining issues. Proceed to Stage 6P or 6P-R (one always runs), then Stage 7 if human accepts remaining issues.
• FAIL: human resolves 6V-C critical issues, then re-run 6V -> 6R

Critical Rules

1. NEVER make business logic decisions. Ambiguous fixes go to 6V-C.
2. NEVER weaken security. Adding public routes is fine if PRD says public. Removing auth guards is NEVER acceptable.
3. ALWAYS preserve test baseline. Zero test regressions is non-negotiable.
4. ALWAYS typecheck after EVERY fix, not just at the end.
5. ALWAYS verify fixes in the running app, not just in code.
6. NEVER modify auto-generated files (_generated/, .next/, node_modules/).
7. NEVER create database schema changes.
8. If a 6V-B fix introduces a NEW failure of EQUAL or HIGHER severity, revert and move to 6V-C.
9. ALWAYS read component/function context before fixing. Check git blame when a fix seems too simple.
10. For i18n fixes: check ALL language files.
11. For stub pages: ALWAYS include auth guards, loading states, and error handling.
12. If 6V report has zero failures, output a clean report and exit.
13. Maximum 3 internal fix-verify cycles per run (tracked in loop-count.txt — filename preserved for backward compatibility).
14. ALWAYS respect the project's file organization conventions.

Output Specification

Artifact	Path
Remediation Plan	./plancasting/_audits/runtime-remediation/plan.md
Remediation Report	./plancasting/_audits/runtime-remediation/report.md
6V-C Escalations	./plancasting/_audits/runtime-remediation/category-c-escalations.md
Remaining Blockers (after 3 cycles)	./plancasting/_audits/runtime-remediation/remaining-blockers.md
Cycle Counter	./plancasting/_audits/runtime-remediation/loop-count.txt
Baseline Typecheck Log	./plancasting/_audits/runtime-remediation/baseline-typecheck.log
Baseline Tests Log	./plancasting/_audits/runtime-remediation/baseline-tests.log
Last Remediated Commit	./plancasting/_audits/runtime-remediation/last-remediated-commit.txt
Updated 6V Report	./plancasting/_audits/visual-verification/report.md (appended)