easysdd-issue-fix

At this stage, the root cause and solution have been determined (the standard path is in

{slug}-analysis.md

, and the quick path was confirmed verbally during the report stage). Your task is to modify the code according to the solution, verify the effect, and write the repair record.

It sounds straightforward, but the most prone problem in the fix stage is not the code modification itself, but the "casual" impulse that arises during the modification—casually optimizing a bit, casually refactoring a little, casually adding an abstraction. Each item makes sense on its own, but putting them all in one PR makes it impossible for others to distinguish "what exactly was changed to fix the bug this time". The purpose of all the following rules is to stop this impulse.

For shared paths and naming conventions, refer to Section 0 of
easysdd/reference/shared-conventions.md
and the "Where to put files" section of
easysdd-issue
.

Two Entry Points

Standard Path Entry (with {slug}-analysis.md)

Root cause analysis exists and solution is confirmed——Read
```
{slug}-analysis.md
```
, confirm that the frontmatter has
```
doc_type=issue-analysis
```
and
```
status=confirmed
```
, and which solution the user selected in Section 5 "Repair Solution"
Read the full context:
- Full root cause analysis text
- Full problem report text
- All code files located in Section 1 of the root cause analysis
- ```
AGENTS.md
```
- Records related to this issue in the compound directory (search uniformly in
```
easysdd/compound/
```
  , filter by
```
doc_type
```
  as needed):
  - Trick search:
    python easysdd/tools/search-yaml.py --dir easysdd/compound --filter doc_type=trick --filter status=active --query "{issue keywords}"
    ——Confirm that the repair method does not violate existing library usage / pattern suggestions
  - Explore search:
    python easysdd/tools/search-yaml.py --dir easysdd/compound --filter doc_type=explore --query "{issue keywords}"
    ——Confirm that the repair point does not conflict with existing evidence
Confirm the repair starting point——Tell the user "I will modify {file list} according to Solution X, starting the repair", and wait for user confirmation before taking action

Quick Path Entry (without {slug}-analysis.md, triggered directly from easysdd-issue-report)

When entering this entry, the AI has already read the code during the report stage and is confident about the root cause.

Clearly state the root cause to the user: "The {specific code} at
```
{file}:{line number}
```
has {problem description}", and let the user confirm that the root cause judgment is accurate
Provide a repair solution——Where to modify and how to modify (just one or two sentences, no need to write a complete analysis document)
Wait for the user to clearly say 'Yes, modify it this way' before taking action——"I think it's correct, modify directly" is not allowed
Read
```
AGENTS.md
```
Supplement search in the compound directory——The quick path also requires using
```
search-yaml.py --dir easysdd/compound
```
to search, check similar tricks with
```
--filter doc_type=trick
```
, and avoid mistaking known boundary conditions for new issues with
```
--filter doc_type=explore
```

Constraints During Implementation

Only Modify Files Stated in the Root Cause Analysis

The repair scope comes from the "Impact Scope" in Section 5 "Recommended Solution" of

{slug}-analysis.md

. Do not modify files outside the scope—even if they look good.

If you find something worth modifying outside the scope, record it as a "casual discovery" without modifying the code:

markdown

> Casual discovery: {file:line number} {brief problem description}. Not within the scope of this repair, can open a separate issue later.

Why is this so strict? The reason is the same as feature-implement——casually modified code is not in the analysis, it cannot be checked during acceptance, and future developers cannot distinguish which changes were made to fix this bug via git blame.

Minimize Changes

The repair changes should only target the root cause, do not introduce new abstractions, new interfaces, or new patterns. If you find that "to fix this properly, you need to refactor X first"——stop, and confirm with the user whether to do the refactoring in this issue or split it into independent work.

Why is this so strict? Bug fixes are naturally narrow-scoped actions. Introducing a new abstraction means this abstraction is only supported by one usage point——a typical case of premature abstraction. Either refactor separately first then fix the bug, or fix the bug then refactor separately, but don't do both in one PR.

Code Quality Reflection Check

Although bug fixes seem small, AI can still drift when writing repair code——adding another special handling in an already long file, adding another method to an already heavy class, adding an

if

branch to bypass some boundary condition. For reflection checks, refer to Section 7 of

easysdd/reference/shared-conventions.md

In issue-fix, this section needs to be more cautious than feature-implement: when a reflection signal is triggered but the conclusion is 'should split', do not do it in this PR by default——record it as a casual discovery according to the "minimize changes" logic, and handle it in separate work later. The only exception is "cannot fix this bug cleanly without splitting", then stop and clearly tell the user "The prerequisite for fixing this bug is {refactoring action}, should it be included or split out to do separately".

Report After Completing Each Change

The repair report template is in the same directory

reference.md

, vague reports are not allowed. Stop and wait for the user's reply after reporting.

Verification Checklist

After modifying the repair code, check each item in the report:

Reproduction Step Verification: Follow the steps in Section 2 of
```
{slug}-report.md
```
to confirm the problem no longer occurs
Expected Behavior Verification: The "expected behavior" described in Section 3 of
```
{slug}-report.md
```
now occurs as expected
Impact Scope Regression: "Potentially Affected Modules" in Section 4 of
```
{slug}-analysis.md
```
——Run the most basic smoke test for each module to confirm no new issues are introduced by the repair
Frontend Change Browser Verification (if applicable): Mandatory requirement in AGENTS.md, cannot rely solely on typecheck
Relevant Tests Pass: If there are tests covering the repair area, run them

When Repair Fails to Take Effect: Upgrade to Log Debugging

If after going through the verification checklist you find that the problem still reproduces or the behavior is inconsistent with expectations, do not repeatedly trial and error based on the original guess——switch to log debugging mode and re-collect runtime evidence.

Why switch? The essence of repeated trial and error is guessing what other possibilities exist under the original hypothesis, but if the original hypothesis itself is wrong, more guessing is just going in circles. Logs will force you to look at actual runtime data, which often reveals where the original hypothesis was wrong at a glance.

Log debugging steps, user prompt words for retrieving logs, and loop limits are in the same directory

reference.md

Write {slug}-fix-note.md

After verification passes, create

{slug}-fix-note.md

in the issue directory (location refers to the "Where to put files" section of

easysdd-issue

) to record the complete loop of this repair. Both the standard path template and quick path template are in the same directory

reference.md

Exit Conditions

All modified files have been submitted or listed
All items in the verification checklist are checked
```
{slug}-fix-note.md
```
has been created and filled completely (use the standard template for the standard path, quick path template for the quick path)
No unresolved "casual discoveries" (all have been added to the subsequent issue list)
No changes outside the scope (or confirmed with the user)
User clearly confirms the repair is complete

Final Commit

Follow the rules in Section 4 "Final Commit (scoped-commit)" of

easysdd/reference/shared-conventions.md

. Specific points for this stage:

Commit Scope: Repair code,
```
{slug}-fix-note.md
```
, and
```
{slug}-report.md
```
/
```
{slug}-analysis.md
```
that were actually updated together this time
After the repair loop is completed, tell the user "Repair verification is completed,
```
{slug}-fix-note.md
```
has been archived", then immediately ask if commit is needed

After Exit

Tell the user: "Issue repair is completed, workflow is closed. Problem report ({slug}-report.md) + root cause analysis ({slug}-analysis.md) + repair record ({slug}-fix-note.md) have been archived."

Then ask one sentence each in the recommended closing order for "issue-fix" in Section 3 of

easysdd/reference/shared-conventions.md

(skip immediately if the user says "no"):

This repair exposed a pitfall / experience worth reusing → "Do you need to document this pitfall into a learning document? (Follow
```
easysdd-learning
```
, will be written into
```
easysdd/compound/
```
)"
This repair documented long-term constraints, conventions, or technical decisions → "Do you need to archive this decision? (Follow
```
easysdd-decisions
```
)"
Finally, ask again if you need to commit this repair on behalf of the user. When the user agrees, follow the final commit rules until the commit is completed.

You can suggest:

Put the files in the issue directory and code changes in the same commit for easy future tracing
Handle subsequent issues from "casual discoveries" in a new round of
```
easysdd-issue-report
```
, do not include them in this PR

If during the repair you find that the problem is actually a feature gap (not a bug), suggest the user open a separate

easysdd-feature

workflow to handle it, do not secretly implement new features in the issue workflow.

Common Pitfalls

Declare "fixed" without going through the verification checklist after modifying the code
Casually modified code outside the scope of the root cause analysis
Introduced new abstractions / interfaces during repair but did not stop to confirm with the user
Declared workflow completed without creating
```
{slug}-fix-note.md
```
Found regression issues in the impact scope but wrote "minor impact, can be ignored" in the report——must fix until it's clean
Made frontend changes but did not run in the browser, only did typecheck and reported passing
Ended the workflow without the user clearly saying "repair completed"
When repair failed to take effect, continued to guess and trial and error based on the original hypothesis instead of switching to log debugging
Submitted code without cleaning up temporary log statements after log debugging
Did not ask the user if they need to commit on their behalf when closing the workflow
Directly
```
git commit
```
without the user's explicit consent

easysdd-issue-fix

NPX Install

Tags

SKILL.md Content (Chinese)

easysdd-issue-fix

Two Entry Points

Standard Path Entry (with {slug}-analysis.md)

Quick Path Entry (without {slug}-analysis.md, triggered directly from easysdd-issue-report)

Constraints During Implementation

Only Modify Files Stated in the Root Cause Analysis

Minimize Changes

Code Quality Reflection Check

Report After Completing Each Change

Verification Checklist

When Repair Fails to Take Effect: Upgrade to Log Debugging

Write {slug}-fix-note.md

Exit Conditions

Final Commit

After Exit

Common Pitfalls