| name | agents-regression-capture |
| description | Turns fixed unique bugs into regression tests, static guards, checklist wiring, and lessons so the same failure class is caught early. Auto-use immediately after resolving a non-trivial bug, race, lifecycle issue, flaky test, or one-off production failure that could recur; also when the user asks to harden a fix or prevent recurrence. |
Regression capture (post-fix hardening)
Mandatory closeout after any non-trivial bug fix in this repo — same turn as
the fix, before claiming done. Implements the Missing Capability Loop in
docs/agent_knowledge_base.md.
Pair with systematic-debugging during investigation and
agents-validation-testing when wiring guards.
Do not duplicate: validation chooser and guard catalog →
agents-validation-testing; this skill owns capture ladder + durable memory.
Auto-trigger
Invoke when any apply:
- Root cause found and code fix landed (or user confirms fix verified)
- Race, lifecycle, async supersession, stale sync, layout overflow, initState
InheritedWidget, or offline-first merge bug class
- Flaky test fixed by behavior change (not only test timing tweak)
- User says: prevent recurrence, add regression, harden, guard, capture lesson
Skip (record reason in report)
- Docs/format/rename only
- Obvious typo with no behavioral contract
- Bug class already covered by existing test + guard on touched paths
- External-only outage with no repo contract change
Workflow
Answer "What went wrong, how was it fixed, what stops recurrence?" then run
the ladder below. Smallest durable artifact that encodes the class, not the
single line.
Progress:
- [ ] 1. Name the bug class (one sentence)
- [ ] 2. Pick capture lane(s)
- [ ] 3. Implement smallest guard(s)
- [ ] 4. Wire into checklist / regression routing
- [ ] 5. File durable memory
- [ ] 6. Verify guards fail before fix / pass after
- [ ] 7. Report capture proof
1. Name the bug class
Template:
- Symptom: what the user saw
- Root cause: why it happened (mechanism, not blame)
- Fix: what changed
- Class: generalized pattern (e.g. "mutation success treated as failure after RequestIdGuard supersession")
2. Pick capture lane(s)
Use the first lane that can catch recurrence cheaply; add others only when
needed.
| If the class is… | Prefer | Also consider |
|---|
| Wrong outcome for given inputs/state | Focused unit/cubit/widget test | Extend anchor in docs/testing_overview.md § Regression test anchors |
| Repeatable anti-pattern in code shape | tool/check_<topic>.sh static guard + tool/fixtures/ bad/good samples | .cursor/rules/*.mdc only when agents/humans need prose |
| Path-dependent integration behavior | Widget/integration test; register in tool/check_regression_guards.sh | tool/integration_selective_map.json when journey-specific |
| Offline-first / stale remote / TOCTOU | Repository test per docs/offline_first/dont_overwrite_guide.md | tool/check_offline_first_remote_merge.sh inventory |
| UI layout / overflow | *_regression_test.dart + area script (tool/check_row_action_overflow.sh, etc.) | docs/design_system.md if shared component contract |
Extend existing anchors before adding parallel tests — see
docs/testing_overview.md § Repo
testing conventions.
3. Implement guards
Regression test
- Name:
*_regression_test.dart or focused test with explicit bug-class name
- Must fail on pre-fix behavior (revert locally to confirm when practical)
- Cover the failure path, not only happy path
Static guard (syntactic/structural)
4. Wire automation
Minimum wiring checklist:
Run validation doc sync when catalog/checklist touched:
bash tool/fix_validation_docs.sh && bash tool/validate_validation_docs.sh
5. File durable memory
| Audience | Where |
|---|
| Agent + humans, reusable pattern | tasks/lessons.md — use template (what went wrong / fix / pattern / preventive rule / evidence) |
| Why this PR hardened the repo | docs/changes/YYYY-MM-DD_<slug>.md — summary, bug class, verification commands |
| Index | one line in docs/changes/README.md when change note added |
| Regression anchor table | docs/testing_overview.md when new anchor area |
Do not add ## Learned bullets to AGENTS.md; file in tasks/lessons.md
or owning doc per operator prefs.
6. Verify
flutter test <path> [--name "<case>"]
bash tool/check_<name>.sh --paths tool/fixtures/<name>/bad_*.dart
bash tool/check_<name>.sh --paths tool/fixtures/<name>/good_*.dart
CHECK_REGRESSION_GUARDS_MODE=auto tool/check_regression_guards.sh --paths <touched-path>
./bin/checklist-fast
7. Report capture proof
Include in task closeout (with fix proof):
## Regression capture
- Bug class: …
- Tests: …
- Static guard: … (or N/A)
- Checklist wiring: …
- Lessons/changes: …
- Verified: commands run + outcome
Examples (repo)
| Bug class | Capture |
|---|
| RequestIdGuard supersession → false failure UI | tool/check_mutation_success_after_guard.sh, therapy/chat regression tests, docs/changes/2026-06-15_mutation-success-guard.md |
initState context.cubit< | Guard regex update, test/shared/inherited_widget_lifecycle_regression_test.dart |
| Stale remote overwrites local | offline_first_*_repository_test.dart, tool/check_offline_first_remote_merge.sh |
| Row/action overflow | test/shared/widgets/row_overflow_regression_test.dart, tool/check_row_action_overflow.sh |
Related
