Apply a targeted fix based on a diagnosis, then verify it passes. Reverts on failure. Tracks every attempt in debug-log.md to avoid repeating failed approaches.
Apply a fix based on the diagnosis from /debug-diagnose, then verify it works. If verification fails, revert and report.
$ARGUMENTS
The arguments should contain the diagnosis output from /debug-diagnose. If no arguments, check the conversation for the most recent diagnosis.
Before touching any code:
Check debug history: Read debug-log.md — has this exact approach been tried before? If yes, STOP and try a different angle.
Create a save point:
# Stash or note the current state so we can revert cleanly
git stash push -m "debug-savepoint-$(date +%s)" --include-untracked 2>/dev/null
git stash pop # immediately restore — we just want the stash as a safety net
# Or simply note the current HEAD
SAVE_POINT=$(git rev-parse HEAD)
echo "Save point: $SAVE_POINT"
# Run the specific failing test/command from the diagnosis
# If it now passes without any fix, the issue may have been resolved by another agent
If the issue no longer reproduces, report "Issue no longer reproduces — may have been fixed by another agent" and exit.
Based on the diagnosis, apply the smallest possible fix. Rules:
|| null, or suppressing errors is NOT a fix unless the diagnosis specifically calls for error handlingspecs/*/contracts/interfaces.md. If it conflicts, flag to the team lead before proceeding.Visual/UI bugs:
Runtime errors:
as any)Logic bugs:
Performance:
Integration/API:
Flaky tests:
waitForTimeout with proper waitFor/assertion-based waitsBuild failures:
@ts-ignore)npm installRun verification appropriate to the issue type:
Visual (MANDATORY — full E2E suite, not just the fixed flow):
# First: verify the specific fix
cd .kiln/qa && npx playwright test --config=playwright.config.ts --grep "[test-name]" 2>&1
# Then: run the FULL E2E suite to catch regressions (NON-NEGOTIABLE for UI fixes)
cd .kiln/qa && npx playwright test --config=playwright.config.ts 2>&1
PASS if: the specific test passes on desktop AND mobile viewports, AND the full E2E suite has no new failures compared to before the fix. A fix that breaks another flow is NOT a fix — revert and try a different approach.
Runtime:
# Re-run the failing test
npm test -- --grep "[test-name]" 2>&1
PASS if: test passes with exit code 0.
Logic:
# Re-run the failing test AND related tests
npm test -- --grep "[test-pattern]" 2>&1
PASS if: all assertions pass, output matches expected values.
Performance:
# Re-run the performance measurement
# Compare against the threshold from the diagnosis
PASS if: metric is below the acceptable threshold.
Integration:
# Re-run the API test or curl command
curl -v [endpoint] 2>&1
# OR re-run integration test
npm test -- --grep "[integration-test]" 2>&1
PASS if: correct status code and response shape.
Flaky:
# Run the test 10 times — ALL must pass
for i in $(seq 1 10); do
npm test -- --grep "[test-name]" 2>&1 | tail -1
done
PASS if: 10/10 runs pass.
Build:
npm run build 2>&1
PASS if: build succeeds with exit code 0.
After the specific fix passes, run a broader check to make sure nothing else broke:
# Run the full unit/integration test suite
npm test 2>&1
For UI fixes — E2E regression check is MANDATORY (in addition to unit tests):
# Run the full Playwright E2E suite
cd .kiln/qa && npx playwright test --config=playwright.config.ts 2>&1
This catches visual regressions (layout shifts, broken navigation, CSS cascade issues) that unit tests cannot detect. UI fixes that pass unit tests but break other flows in the browser are NOT acceptable.
If the full suite has new failures that didn't exist before your fix, your fix introduced a regression. Revert and try a different approach.
debug-log.md:### Attempt N — [technique]: [approach]
**Action**: [what was changed, file:line]
**Result**: PASS
**Verification**: [test output summary]
**Regression check**: [full suite result]
**Commit**: [will be committed]
git add [changed files]
git commit -m "fix: [concise description of what was fixed and why]
Root cause: [one-line root cause]
Diagnosed via: [technique used]
Verified by: [test/command that confirms fix]"
git checkout -- [changed files]
# Or if files were added:
git clean -fd [new files]
debug-log.md:### Attempt N — [technique]: [approach]
**Action**: [what was changed]
**Result**: FAIL
**Why it failed**: [specific reason — what the verification showed]
**Reverted**: yes
Ensure debug-log.md captures everything for future reference. If the file doesn't exist, create it:
# Debug Log
This file tracks all debugging attempts across the pipeline. It prevents repeating
failed approaches and creates an audit trail for the retrospective.
---
Every attempt (pass or fail) gets logged. This is the historical memory that the debugger agent reads before each attempt.
|| null, @ts-ignore, as any)