bug-fixing

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.