Menu
Produce a bugfix spec from a bug report — 3-section behavioral delta format instead of full design doc. Dispatched by coder-task, not invoked directly.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Audit repository test suites for low-value, brittle, duplicative, or AI-generated tests. Use when Codex needs to review tests across a single project or monorepo, identify tests to delete or merge, upgrade weak tests, consolidate repeated setup into helpers, or produce a precise test quality cleanup plan.
Use when you have a plan directory from decomposing-specs and need to execute it — loads phases on demand, dispatches phase-elaborator for sketched phases, runs implementers with size-scaled phase reviews, and validates the full spec at the end
Use when you have a design spec from writing-specs and need to break it into an implementable, phased task plan with behavior-focused verification before writing any code
Use when given a GitHub issue URL to autonomously implement — forks the repo, writes a spec if needed, decomposes into tasks, implements, and opens a PR
Use when given a GitHub issue URL to autonomously implement — forks the repo, writes a spec if needed, decomposes into tasks, implements, and opens a PR
Use when a GitHub issue receives new comments during autonomous work — decides whether to update the spec and re-decompose, or just make the change inline
| name | bugfix |
| description | Produce a bugfix spec from a bug report — 3-section behavioral delta format instead of full design doc. Dispatched by coder-task, not invoked directly. |
Produce a structured bugfix specification that captures what's broken, what correct behavior looks like, and what existing behavior must be preserved. Output: docs/plans/YYYY-MM-DD-issue-${ISSUE_NUMBER}-design.md. This skill is dispatched by coder-task when it classifies an issue as a bug — it is not a standalone entry point.
digraph bugfix {
"Receive issue context" [shape=box];
"Explore reproduction path" [shape=box];
"Draft 3-section spec" [shape=box];
"Write EARS requirements" [shape=box];
"Write to docs/plans/" [shape=box];
"Done" [shape=doublecircle];
"Receive issue context" -> "Explore reproduction path";
"Explore reproduction path" -> "Draft 3-section spec";
"Draft 3-section spec" -> "Write EARS requirements";
"Write EARS requirements" -> "Write to docs/plans/";
"Write to docs/plans/" -> "Done";
}
This skill receives context from coder-task:
Three sections. Intentionally simpler than a full design doc — bugfixes are behavioral deltas, not system design exercises.
Describe the observed defect using EARS format for precision:
WHEN [trigger condition] THE SYSTEM [incorrect behavior observed]
Include:
EARS requirements for the correct behavior. Each must be testable and unambiguous.
WHEN [same trigger condition] THE SYSTEM SHALL [correct behavior]
These become the fix tests — they must fail before the fix and pass after.
EARS requirements for existing behaviors that must continue working after the fix. Use the SHALL CONTINUE TO pattern:
THE SYSTEM SHALL CONTINUE TO [existing behavior that works correctly]
For each preserved behavior, cite a verification anchor — an existing test that covers it:
Verification anchor: tests/path/to/existing.test.ts
These become the preservation tests — they must pass both before and after the fix.
If you are uncertain which existing behaviors to protect, explore the test suite in the impact area before proceeding. When in doubt, list more preserved behaviors rather than fewer.
The bugfix spec implicitly defines two categories of tests, formalized by the "Bug Fix Paradox":
When this spec is decomposed into tasks, the task list must include both categories explicitly. The first task is always a reproduction test demonstrating the Fix Property fails (proving the bug exists).
During drafting, if you make assumptions about the bug's scope, trigger conditions, or expected behavior, mark them:
[NEEDS CLARIFICATION: <specific question> — assumed: <your best guess>]
Maximum 3 markers. In autonomous mode (coder-task), these are posted to the GitHub issue and execution proceeds with the assumed answers.
This template does not include Goals/Non-Goals, System Design, or Libraries sections from the full writing-specs format. Bugfixes are behavioral deltas — the system design already exists and is not changing. If a bug requires architectural changes, it should be handled as a feature via writing-specs instead.
Most bugfixes produce a short spec (3-5 EARS requirements total). If the spec grows beyond 10 requirements, consider whether this is really a feature request in disguise.
| Mistake | Fix |
|---|---|
| No reproduction test | First task must always be a test proving the bug exists |
| Fixing without understanding root cause | Trace the bug's code path before writing Expected Behavior |
| Missing preservation tests | List existing behaviors in the impact area and cite verification anchors |
| Scope creep beyond the bug | Bugfix specs fix one bug — additional improvements belong in a separate spec |
| Empty Unchanged Behavior section | If you can't identify preserved behaviors, you haven't explored the impact area enough |
See skills/writing-specs/examples/ for bugfix and brownfield examples:
bugfix-small-regression.md — Rate limiter over-counting after a library upgradebrownfield-delta-change.md — Adding retry logic to an existing webhook system