| name | bug-fixing |
| description | Fix bugs with a test-first workflow. Use when the user reports a bug, asks to fix a defect, or describes unexpected behavior. Triggers on: bug, fix, defect, broken, regression, not working, unexpected behavior. |
Bug-Fixing Workflow
0. Locate the bug
Identify which surface fails: managed session, waitForTextInSurface, replay, PTY buffer, diagnostics, etc.
1. Choose test level
- If the bug is pure library logic (replay, matching, messages), add or extend a
tests/*.test.ts case that drives startManagedTtySession, waitForTextInSurface, or another appropriate entry point.
- If the bug only shows up in a downstream project (e.g. Cypress task wiring), fix may belong in this repo (API/diagnostics) and the consumer; still add a tty-assert test if the contract is wrong here.
2. Write a failing test that reproduces the bug
- Minimum test — one test (or the smallest addition) that covers the bug.
- Assert observable output — assertion result, thrown message, diagnostic text — not private fields.
- Prefer expected-vs-actual —
expect(actual).toEqual(expected) or substring checks that show what broke.
- Guard against false positives — the test must fail when the bug is present.
- Prefer updating over adding — if an existing test should have caught this, strengthen that test.
3. Confirm the failure
- Run
pnpm test and verify the new behavior fails.
- Confirm the failure is for the right reason (not missing
canvas, wrong fixture path, etc.).
- If the message is unclear, improve the assertion before fixing production code.
4. Fix the bug
- Implement the smallest change that makes the test pass.
- Remove debug-only code.
5. Confirm green
- Run the new test and related tests in the same file / area.
- Run
pnpm lint.
6. Refactor
- If tests overlap, simplify; keep one clear story per behavior.
