| name | pipeline-bugfix |
| description | Execute a Bug Fix pipeline: environment check, diagnosis, fix, test, regression check, documentation, commit & PR, code review, test verification, review verdict, merge, and retrospective. Invoke with /pipeline-bugfix followed by the bug report.
|
Bug Fix Pipeline
Run a complete bug fix cycle with diagnosis, targeted fix, regression checking, and quality gates.
Usage: /pipeline-bugfix <bug report / description>
CRITICAL: You MUST execute ALL 13 stages. Do NOT stop after Commit & PR (Stage 8). Stages 9-13 (Code Review, Test Verification, Review Verdict, Merge PR, Retrospective) are mandatory.
Before You Start
- Generate a branch name from the bug report:
fix/<short-slug> (e.g., fix/login-timeout)
- Initialize state file (Step 0): Follow the Step 0: Initialize State File procedure from pipeline-shared. This is the FIRST action — creates
.pipeline-state/<branch-name>.json from templates/bugfix-state.json. If it already exists, this is a resume.
- Follow the Configuration Gathering procedure from pipeline-shared to identify project config
- Note the project's pr_target_branch (default:
main)
Stage 1: Environment Check
Follow the Environment Check procedure from pipeline-shared.
Gate: ENV_OK required.
On ENV_FAILED: Retry once. If retry fails → STOP PIPELINE.
Stage 2: Conflict Check
Follow the Conflict Check procedure from pipeline-shared.
Gate: MERGE_CLEAN required.
On MERGE_CONFLICTS_FOUND → STOP PIPELINE.
Stage 3: Diagnosis
Investigate the codebase, identify the root cause, and propose a fix.
Instructions
- Read the bug report carefully
- Search the codebase for relevant code paths
- Identify the root cause (not just the symptom)
- Propose a targeted fix
- Scope check: Compare what you found against the bug report. If you found violations/issues in MORE files or locations than described, output on its own line:
SCOPE_EXPANDED: found X violations across Y files (spec described N)
This is informational — continue with the full diagnosis.
Gate
This stage always passes (informational). The diagnosis output will be referenced by Fix and Regression Check.
Stage 4: Fix
Apply the fix based on the diagnosis from Stage 3.
Instructions
- Implement the fix — keep changes minimal and focused
- Only fix what the diagnosis identified as the root cause
- Do not refactor surrounding code or fix unrelated issues
- Edge cases: Verify the Edge Case Checklist from pipeline-shared
- Clean git state: Follow the Clean Git State procedure from pipeline-shared
If the branch already has commits from a previous attempt, build on that work — do NOT redo what's already done.
Gate
Stage passes if fix completes without errors. Proceed to testing.
Stage 5: Test Execution
Follow the Test Execution procedure from pipeline-shared.
Gate: TESTS_PASSED required.
On TESTS_FAILED: Go back and fix the failing code, then re-run tests (attempt 2 of 2). If tests still fail → STOP PIPELINE.
Stage 6: Regression Check
Verify the fix doesn't introduce regressions and actually addresses the root cause.
Instructions
-
Root cause verification: Cross-reference the Diagnosis stage output (Stage 3) against the fix. Verify the root cause identified was actually addressed, not just a symptom. Flag if the fix diverged from the diagnosis.
-
Regression check: Verify no related functionality is broken
-
Edge case review: Confirm edge cases are handled
Gate
- Pass:
REGRESSION_PASSED — no regressions found
- Fail:
REGRESSION_FAILED — followed by details
On REGRESSION_FAILED (attempt 1): Fix the issues, then re-check.
On REGRESSION_FAILED (attempt 2): Rewind to Stage 3 (Diagnosis). The original diagnosis may have been incomplete. Re-investigate with the regression context. Then re-fix from Stage 4 onward. Maximum 1 rewind. If second pass also fails → STOP PIPELINE.
Stage 7: Documentation
Follow the Documentation procedure from pipeline-shared.
Gate: DOCS_UPDATED (always passes).
Stage 8: Commit & PR
Follow the Commit & PR procedure from pipeline-shared.
Use conventional commit format: fix: <description>
Gate: PR_CREATED, PR_EXISTS, or PR_SKIPPED.
After this stage completes, you MUST continue to Stage 9. The pipeline is NOT done.
Stages 9-13: Review, Verify, Merge, Retrospective
These stages run as subagents to ensure they execute with fresh context. This prevents context compression from losing the review instructions.
Stage 9-11: Code Review + Test Verification + Review Verdict
Use the Agent tool to spawn a subagent with this prompt:
You are reviewing PR #<pr_number> for a bug fix. The project directory is <project_path>. The PR targets <pr_target_branch>.
Step 1 — Code Review: Run git diff <pr_target_branch>...HEAD. Read changed files. Check for docs/PULL_REQUEST_CHECKLIST.md and use it if found. Review for: correctness, security, testing gaps (bug fix MUST have regression test), code quality, documentation (CHANGELOG updated for fix), performance. Flag auto-reject triggers.
Step 2 — Test Verification: Run the project test suite. Report pass/fail.
Step 3 — Review Verdict: Synthesize findings. Decide: APPROVE, REQUEST_CHANGES, or COMMENT.
Step 4 — MANDATORY: Post review to GitHub PR. Run:
gh pr review <pr_number> --comment --body "<formatted review with checklist, findings, and verdict>"
If REQUEST_CHANGES, use --request-changes instead. If project has pr/feedback/, save there too.
Step 5 — Output exactly one of: APPROVE, REQUEST_CHANGES, or COMMENT.
- If
APPROVE → proceed to Stage 12
- If
REQUEST_CHANGES → fix issues, re-commit, re-push, re-run subagent. Second failure → STOP PIPELINE.
Stage 12: Merge PR
Use the Agent tool to spawn a subagent:
Approve and merge PR #<pr_number> in <project_path>.
gh pr merge <pr_number> --squash --delete-branch
Do NOT run gh pr review --approve — GitHub blocks self-approval.- Output PR_MERGED or MERGE_FAILED.
- If
PR_MERGED → proceed to Stage 13
- If
MERGE_FAILED → retry once. Still failing → STOP PIPELINE.
Stage 13: Retrospective
Use the Agent tool to spawn a subagent:
You are writing a retrospective for a completed bug fix pipeline. Task: <task description>. Project: <project_path>. PR #<pr_number>.
Run git log --oneline <pr_target_branch>..HEAD. Evaluate: quality (1-5), what went well, lessons learned, improvements, IDEA:/TOOL: lines.
You MUST post the retrospective to these two places. This is not optional.
gh pr comment <pr_number> --body "## Pipeline Retrospective\n\n**Quality**: X/5\n\n### What Went Well\n- ...\n\n### Lessons Learned\n- ...\n\n### Suggested Improvements\n- IDEA: ..."- Append to
.pipeline-log.md (create if needed, ensure in .gitignore).
Output RETRO_COMPLETE when both posts are done.
The pipeline is now complete.
Stop Conditions
ENV_FAILED after retryMERGE_CONFLICTS_FOUNDTESTS_FAILED after retry (Stage 5 or 10)REGRESSION_FAILED after retry + rewindMERGE_FAILED after retry
Rewind Rules
| Stage | Can Rewind To | Max Rewinds | Trigger |
|---|
| Stage 6 (Regression Check) | Stage 3 (Diagnosis) | 1 | REGRESSION_FAILED after retry |
