# Bug Fixing

> 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.

- Skill: `terryyin/bug-fixing` (Agent Skill)
- Install (CLI): `npx skillmds@latest add terryyin/bug-fixing`
- Raw SKILL.md: https://api.skillmd.com/api/skills/terryyin/bug-fixing/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: terryyin (https://skillmd.com/u/terryyin)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/terryyin/bug-fixing

---


# 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.