bugfix-workflow

Bugfix Workflow

When to use

The user wants to fix a bug, not add a feature
The bug is not easy to locate directly and root cause analysis is needed first
The fix scope must be controllable

Not applicable:

New features, refactoring, architecture upgrades
Intentionally changing existing product behavior
Only changing copy, formatting, comments, or dependency versions
Bugs that are too simple and can be fixed directly

Archiving conventions

By default archive to:

.cursor/skills/bugfix-workflow/archives/<bug-id>/bugfix.md
.cursor/skills/bugfix-workflow/archives/<bug-id>/design.md
.cursor/skills/bugfix-workflow/archives/<bug-id>/tasks.md
.cursor/skills/bugfix-workflow/archives/<bug-id>/assets/

Requirements:

<bug-id> Use a unique, short, semantically clear kebab-case
Name focuses on the defect itself; prefer "affected object + incorrect behavior"
If the user specifies an archive name or path, follow the user's requirements
If it is only a temporary analysis and the user explicitly says not to archive, it can be skipped
Supporting materials such as screenshots, logs, reproduction HTML, code snippets, and diff excerpts go by default into assets/
Documents should preferentially reference assets/within the archive, and should not continue to reference the issue temporary directory or external paths
Only archive materials directly related to the current defect

By default do not read historical archives; only when the user explicitly requests it, the current bug is highly similar to a certain archive, or a regression source needs to be compared, read the few most relevant archives.

Workflow

1. Bugfix Analysis

First write bugfix.md. Core required fields:

Current Behavior (Defect)
Expected Behavior (Correct)
If necessary, additionally add Unchanged Behavior (Regression Prevention)

Write as close to EARS as possible:

WHEN [条件] THEN the system [错误行为]
WHEN [条件] THEN the system SHALL [正确行为]
WHEN [条件] THEN the system SHALL CONTINUE TO [必须保持的行为]

Add as needed:

Reproduction conditions
Input boundaries or preconditions
Affected modules
Code or behavior that is explicitly not expected to be modified
Existing screenshots or reproduction snippets: assets/ references

See template at bugfix-template.md。

2. Design

At bugfix.md after the boundary is clarified, then write design.md. Core required fields:

What the root cause is
How the root cause is verified
Where the minimal fix surface is

Add as needed:

Which Unchanged Behavior need to be proven by tests
Which assets/ materials support the root cause judgment

If there are multiple approaches, prioritize comparing the change surface, regression risk, and impact on existing API / UI / state machines.

See template at design-template.md。

3. Tasks (optional)

If tasks.mdneeds to be written, the tasks must cover three types of verification:

The bug indeed exists
The bug has been fixed
If there is adjacent behavior risk, additionally add that unaffected scenarios continue to work normally

Prefer adding automated tests; if automation is not possible, clearly write manual verification steps and observation points. If there are test blocking logs, failure screenshots, or minimal reproduction snippets, they should also be archived to assets/ and referenced in the document.

See template at tasks-template.md。

Execution requirements

First confirm the bug scope, then write the document, then change the code.
If there are supporting materials, first organize them into archives/<bug-id>/assets/ and name them consistently.
After implementation, run the minimum necessary test set; if adjacent behavior risks exist, then cover adjacent invariant scenarios as well.
When reporting, clearly state the root cause, change boundaries, newly added or updated tests, and risks that remain unverified.

Hard rules

Do not state a "guessed root cause" as established fact; mark the evidence first
Do not replace a bugfix with a vague "optimization"
Do not refactor unrelated modules in passing unless the fix itself is blocked by them