Bug walkthrough
One bug, from report to review, the way an agent following swe handles it.
“The app says my settings were saved, but they disappear after refresh.”
An illustrative example, not a captured run: the app, files and results are made up. Each step links the swe rule it follows, at the pinned version.
1Understand
Ready when: The failure can be repeated, and “saved” has a clear meaning.
Turn email notifications off, save, then refresh. Compare what the page says with what it loads.
Example: off → Save → “Saved” appears → refresh → notifications are on again.
If not: If the failure cannot be repeated, ask for the missing steps instead of guessing at a fix.
Source: reproduce first
2Explain
Ready when: The code shows the cause, and the intended behavior is checked.
Trace Save and page load. Save updates memory only; a refresh reads the old stored value.
Example: SettingsForm.tsx never calls the existing preferences store. The docs say saved settings survive a refresh.
example · the values are made up INTENT: code does not save the preference, only hold it in memory; the failing check/task expects the saved preference to survive a refresh; the spec (README/docs/docstring) says saved settings survive a refresh
If not: If the code, the task and the docs disagree, say so and name which one wins. Ask only when that order cannot decide it.
Source: the INTENT line · the intent gate
3Plan
Ready when: The files, the change and the check are written down before any edit.
Take the bugfix route: connect Save to the existing store, and test a save followed by a fresh read.
Example: grade 3. That is below 4, so one plan line is enough, and there is no approval stop (that starts at 7).
example · the values are made up plan: SettingsForm.tsx, SettingsForm.test.tsx — save the preference to the existing store — save, recreate the page, read the value back
If not: If the fix turns out to be wider, grade and plan again before going on.
Source: the plan line · plan threshold · approval grade
4Fix
Ready when: A regression test fails before the change and passes after it.
Write a test that saves the setting, recreates the page and reads it back. Then make the fix.
Example: before the fix the test reads “on”, so it catches the bug. After the fix it reads “off”.
If not: If the test passes before the fix, it does not capture this bug. Fix the test first.
Source: failing test first
5Verify
Ready when: The original steps now work, and the project checks pass with fresh output.
Save, refresh and confirm the setting stays. Then run the build, lint and tests.
Example: the setting stays off after a refresh, and can be switched back on.
If not: If a refresh still loses the value, the work is held. A passing test alone does not count. Back to Explain.
Source: the standard checks · the iron law
6Report
Ready when: The handoff names the cause, the change, the checks that ran, what was not checked, and how to verify.
Report what changed and what was really run. Leave the change for your review; the agent never merges.
Example: turn notifications off, save, refresh, confirm they stay off; then repeat with on.
If not: If a check was not run, say so. Never fill the gap with “should work”.
Source: finish checklist · the iron law · do not merge
Then it is your turn: read the change and its evidence, and merge it if you agree. The full bugfix workflow lists everything the agent must hand over.