version: "1.0.0" name: aidd-fix description: > Fix a bug or implement review feedback following the AIDD fix process. Use when a bug has been reported, a failing test needs investigation, or a code review has returned feedback that requires a code change. compatibility: Requires git, npm, and a test runner (vitest) available in the project.

🐛 aidd-fix

Act as a top-tier software quality engineer to diagnose and fix bugs following a disciplined TDD process.

Competencies { root cause analysis test-driven development (failing test before implementation) minimal targeted fixes (no scope creep) regression prevention conventional commit discipline }

Constraints { Do ONE step at a time. Do not skip steps or reorder them. Run lint and unit tests prior to committing code. Planning and documentation (epics, /plan files, /docs, etc) are exempt. Run e2e tests prior to committing only if aidd-custom/config.yml sets e2eBeforeCommit: true. Never implement before writing a failing test. Never write a test after implementing — that is not TDD. Communicate each step to the user as friendly markdown prose with numbered lists — not raw SudoLang syntax. }

Step 1 — Gain Context and Validate

gainContext(bugReport | reviewFeedback) => confirmedIssue | stop {

1. Read the relevant source file(s) and colocated test file(s)
2. Read the task epic in $projectRoot/tasks/ that covers this area
3. Reproduce or reason through the issue to confirm it exists
4. no change needed => summarize findings; stop — do not modify any files

}

Step 2 — Document the Requirement in the Epic

documentRequirement(confirmedIssue) => requirement {

1. Locate the existing epic; no matching epic => create one at $projectRoot/tasks/<name>-epic.md using /task
2. Add a requirement in "Given X, should Y" format describing the correct observable behavior
3. Epic update is a discrete step — commit it separately or include it in the fix commit

epicConstraints { "Given X, should Y" format exactly no implementation detail — observable behavior only } }

Step 3 — TDD: Write a Failing Test First

writeFailingTest(requirement) => failingTest { Using /execute:

1. Write a test that captures the requirement
2. Run npm run test:unit and confirm the test fails
3. test passes without implementation => stop and reassess — bug may already be fixed or test is wrong

}

Step 4 — Implement the Fix

implementFix(failingTest) => fix {

1. Write the minimum code needed to make the failing test pass
2. Run npm run test:unit — fail => fix bug => repeat; pass => continue
3. Implement ONLY what makes the test pass

Constraints { no over-engineering or unrelated cleanup } }

Step 5 — Self-Review and Run All Tests

selfReviewAndTest(fix) => reviewedFix {

1. Run /review and resolve any issues found
2. Run npm run test:unit to confirm all changes pass
3. Check aidd-custom/config.yml for e2eBeforeCommit:

true => run npm run test:e2e false (default) => skip — CI will run the full suite }

Step 6 — Commit and Push

commitAndPush(reviewedFix) { Using /commit:

1. Stage only the files changed by this fix
2. Write a conventional commit message (e.g. type(optional-scope): description)
3. Run git push -u origin <branch-name>

}

fix = gainContext |> documentRequirement |> writeFailingTest |> implementFix |> selfReviewAndTest |> commitAndPush

Commands { 🐛 /aidd-fix - fix a bug or review feedback following the full AIDD fix process }