Bugfix Workflow

Bugfix Workflow: Reproduce → Test → Fix → Verify

Core philosophy: reproduce before you fix, verify after you fix, link everything to the ticket.

Platform & systems

gh issue … / gh pr … below are the GitHub reference. Translate to your tracker per .agents/profile.md § Project systems (jira / gitlab-issues / azure-boards / linear) and your code host's CLI per .agents/workflow.md (GitLab glab, Azure DevOps az repos, Bitbucket bb, Gitea tea). If scout hasn't recorded them, ask before assuming GitHub.

The seven steps

1. Read & understand the bug
2. Reproduce
3. Write a failing test
4. Root cause analysis
5. Implement the fix
6. Verify
7. Document on ticket

1. Read & understand the bug

gh issue view . Identify expected vs actual behavior, files involved, error messages, stack traces, related issues. Post a 🔧 **Investigating** comment on the ticket so the reporter knows work has started.

2. Reproduce

Confirm the bug exists and understand the exact conditions that trigger it. For the full method — UI / API / logic / intermittent attempts and the CONFIRMED / CANNOT-REPRODUCE confirmation gate — use the reproducing-issues skill. UI bugs → Playwright MCP snapshots. API bugs → curl. Logic bugs → minimal reproducer script.

If you cannot reproduce, stop and ask. Do not proceed to fix a bug you cannot observe. Post what you tried and request more details.

Once reproduced, post a ✅ **Reproduced** comment with steps, expected, actual, and frequency (always / intermittent).

3. Write a failing test

Capture the bug as a regression test before fixing. Run it and confirm it fails — that's the whole point. A passing test for an unfixed bug means the test doesn't exercise the bug.

4. Root cause analysis

Trace the bug to its exact cause — for the full method (execution-path tracing, root-cause classification, confidence, impact/regression analysis) use the root-cause-analysis skill. Locate the code, trace execution from entry point to failure, classify the cause (logic / data / concurrency / config / integration / resource), and assess blast radius — what else uses this code, could the fix break anything else?

Post a 🔍 **Root Cause** comment with location (file:line), cause, impact, and fix approach.

5. Implement the fix

Minimal, focused. Fix the root cause — only the root cause. Don't refactor neighboring code, don't clean up unrelated style, don't expand scope. A bug fix is not the place for improvements.

6. Verify

The failing test from step 3 now passes. Full test suite still passes. Lint and type checks clean. If anything fails, fix it before proceeding — don't ship a fix that breaks something else.

7. Document on ticket

Post a ✅ **Fixed** comment with root cause summary, what changed, regression test name, and PR number. Commit and open the PR. The completing-a-task skill covers the full commit → PR → notify handoff.

Command recipes

All the gh issue comment heredocs, reproduction patterns, test templates, and verification commands live in [references/commands.md](references/commands.md). Load that file when you need the exact template text.

Anti-Patterns

• Don't fix without reproducing first
• Don't skip the failing test — no test = no proof of fix
• Don't refactor while fixing — separate concerns into separate PRs
• Don't close the ticket without documenting what was wrong and what changed
• Don't fix multiple unrelated bugs in one PR

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: arozumenko
• Source: arozumenko/sdlc-skills
• License: MIT

Install and usage instructions live in the source repository linked above.