bugfix
starsforks
How to install bugfix?
dan-the-dev/xp-developer-skills/bugfix
$npx -y skills add dan-the-dev/xp-developer-skills --skill bugfixUse when fixing bugs, regressions, failing tests, or unexpected behavior. Applies a strict test-first bugfix workflow with minimal safe changes, isolated commits, and language-agnostic verification strategies.
SKILL.md
| 1 | # Bugfix TDD |
| 2 | |
| 3 | ## Mission |
| 4 | |
| 5 | Shared delivery rules at boundaries: [`docs/delivery-process.md`](../../docs/delivery-process.md) (§2 verification, §3 change-surface, §4 test strategy, §7 two hats) and [`docs/project-verification.md`](../../docs/project-verification.md), [`docs/test-strategy-selection.md`](../../docs/test-strategy-selection.md). |
| 6 | |
| 7 | Fix bugs safely using a strict RED → GREEN workflow. |
| 8 | |
| 9 | The goal is: |
| 10 | |
| 11 | - reproduce the bug |
| 12 | - create a deterministic failing test |
| 13 | - apply the minimal safe fix |
| 14 | - verify no regressions |
| 15 | - preserve reviewability and isolation |
| 16 | |
| 17 | This skill optimizes for: |
| 18 | |
| 19 | - correctness |
| 20 | - reproducibility |
| 21 | - safety |
| 22 | - small reversible changes |
| 23 | |
| 24 | NOT for: |
| 25 | |
| 26 | - speed |
| 27 | - cleanup |
| 28 | - optimization |
| 29 | - refactoring |
| 30 | |
| 31 | --- |
| 32 | |
| 33 | ## Core Principles |
| 34 | |
| 35 | - Tests are the source of truth |
| 36 | - Never fix behavior before reproducing it |
| 37 | - Every bugfix must be reproducible |
| 38 | - Prefer the smallest possible change that **restores the violated invariant**, not one that only hides the symptom |
| 39 | - Separate reproduction from resolution |
| 40 | - Preserve system stability |
| 41 | - Keep commits isolated and reviewable |
| 42 | |
| 43 | --- |
| 44 | |
| 45 | ## Language-Agnostic Rules |
| 46 | |
| 47 | This skill MUST adapt to the current repository stack. |
| 48 | |
| 49 | The agent should: |
| 50 | |
| 51 | - detect the language and framework in use |
| 52 | - identify existing testing conventions |
| 53 | - reuse project-native tooling |
| 54 | - follow existing repository patterns |
| 55 | |
| 56 | Examples: |
| 57 | |
| 58 | - JavaScript/TypeScript → npm/pnpm/jest/vitest/playwright |
| 59 | - Python → pytest/unittest |
| 60 | - Go → go test |
| 61 | - Java → junit/maven/gradle |
| 62 | - Ruby → rspec |
| 63 | - Rust → cargo test |
| 64 | |
| 65 | Never assume: |
| 66 | |
| 67 | - package manager |
| 68 | - test runner |
| 69 | - framework |
| 70 | - directory structure |
| 71 | |
| 72 | Always inspect the repository first. |
| 73 | |
| 74 | --- |
| 75 | |
| 76 | ## Mandatory Workflow |
| 77 | |
| 78 | ### 0. Synchronize Repository |
| 79 | |
| 80 | Required steps: |
| 81 | |
| 82 | 1. checkout main branch |
| 83 | 2. pull latest changes |
| 84 | 3. create isolated bugfix branch |
| 85 | |
| 86 | Branch format: |
| 87 | |
| 88 | bugfix/{ticket}-{short-description} |
| 89 | |
| 90 | Examples: |
| 91 | |
| 92 | - bugfix/STR-142-null-email-validation |
| 93 | |
| 94 | - bugfix/PLAT-201-invalid-date-format |
| 95 | |
| 96 | - bugfix/fix-missing-user-mapping |
| 97 | |
| 98 | Rules: |
| 99 | |
| 100 | - lowercase |
| 101 | |
| 102 | - hyphen-separated |
| 103 | |
| 104 | - concise and descriptive |
| 105 | |
| 106 | - description must summarize the bug behavior |
| 107 | |
| 108 | - avoid generic names like: |
| 109 | |
| 110 | - fix-bug |
| 111 | |
| 112 | - issue-fix |
| 113 | |
| 114 | - quick-patch |
| 115 | |
| 116 | Ticket handling: |
| 117 | |
| 118 | - if a ticket identifier exists in the initial request, include it |
| 119 | |
| 120 | - otherwise omit the ticket portion |
| 121 | |
| 122 | The agent should automatically generate a meaningful short description derived from: |
| 123 | |
| 124 | - observed failing behavior |
| 125 | |
| 126 | - affected domain |
| 127 | |
| 128 | - expected correction |
| 129 | |
| 130 | --- |
| 131 | |
| 132 | ### 1. Understand the Failure |
| 133 | |
| 134 | Before writing code: |
| 135 | |
| 136 | - complete a brief **test strategy** note per [`test-strategy-selection.md`](../../docs/test-strategy-selection.md) — e.g. will mutation run after GREEN if configured and logic is branchy? |
| 137 | - identify observed behavior |
| 138 | - identify expected behavior |
| 139 | - identify affected scope |
| 140 | - inspect logs/errors/traces if available |
| 141 | - separate **symptom** (what looks wrong: crash, wrong UI, log noise) from the **invariant** or **contract** that was violated (what the system should **guarantee** under the same conditions) |
| 142 | |
| 143 | Prefer: |
| 144 | |
| 145 | - deterministic reproduction |
| 146 | - automated reproduction |
| 147 | - narrow reproduction scope |
| 148 | |
| 149 | --- |
| 150 | |
| 151 | ### 2. Reproduce the Bug with a Test (RED) |
| 152 | |
| 153 | Create a failing test reproducing the issue. |
| 154 | |
| 155 | Choose the lowest useful test level: |
| 156 | |
| 157 | 1. unit |
| 158 | 2. integration/API |
| 159 | 3. end-to-end |
| 160 | |
| 161 | The test MUST: |
| 162 | |
| 163 | - fail for the correct reason |
| 164 | - be deterministic |
| 165 | - clearly express **expected behavior** — i.e. the **correct observable outcome or invariant** under the failing conditions, not only that “something failed” (see Anti-Patterns: symptom fixes) |
| 166 | - fail before the fix exists |
| 167 | |
| 168 | The reproduction must be sufficient for a reviewer to see **what contract was broken**, not merely that an error path was exercised. |
| 169 | |
| 170 | If reproduction is impossible: |
| 171 | |
| 172 | - STOP |
| 173 | - document constraints |
| 174 | - request clarification |
| 175 | |
| 176 | --- |
| 177 | |
| 178 | ### 3. Verify RED State |
| 179 | |
| 180 | Run the minimal test scope first. |
| 181 | |
| 182 | Examples: |
| 183 | |
| 184 | - single test |
| 185 | - single file |
| 186 | - focused module |
| 187 | |
| 188 | If the test passes unexpectedly: |
| 189 | |
| 190 | - strengthen assertions |
| 191 | - improve reproduction |
| 192 | - verify execution path |
| 193 | |
| 194 | Never continue without confirmed RED. |
| 195 | |
| 196 | --- |
| 197 | |
| 198 | ### 4. Commit RED State |
| 199 | |
| 200 | Stage ONLY test files. |
| 201 | |
| 202 | Commit message: |
| 203 | |
| 204 | test: reproduce bug STR-XXX |
| 205 | |
| 206 | The commit MUST: |
| 207 | |
| 208 | - contain only reproduction logic |
| 209 | - clearly demonstrate the failure |
| 210 | |
| 211 | --- |
| 212 | |
| 213 | ### 5. Apply Minimal Fix (GREEN) |
| 214 | |
| 215 | Modify only the code required to resolve the bug. |
| 216 | |
| 217 | Prefer: |
| 218 | |
| 219 | - local fixes |
| 220 | - minimal behavioral changes |
| 221 | - existing abstractions |
| 222 | - reversible changes |
| 223 | |
| 224 | Avoid: |
| 225 | |
| 226 | - refactoring |
| 227 | - cleanup |
| 228 | - renaming |
| 229 | - architectural changes |
| 230 | - unrelated edits |
| 231 | - **symptom-only** changes that hide the failure without restoring the violated **invariant** (e.g. empty catch, broad default, guard that masks the bug while wrong outcomes remain for other inpu |
People who liked this also viewed
6 picksType
- azure-diagnosticsDebug Azure production issues on Azure using AppLens, Azure Monitor, resource health, and safe triage. WHEN: debug production issues, troubleshoot app service, app service high CPU, app service deploySkillsJul 2026
- systematic-debuggingUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesSkillsJul 2026
- safe-debugRigor Debug / Rigor Audit skill for deep learning research work. Use when the user pastes a traceback, terminal error, CUDA OOM, checkpoint load failure, shape mismatch, NaN loss symptom, or training SkillsMay 2026
- explore-runRigor Improve / Rigor Explore run leaf skill for bounded exploratory evidence in deep learning research repositories. Use when the researcher explicitly authorizes exploratory runs such as small-subseSkillsMay 2026
- minimal-run-and-auditRigor Run skill for README-first deep learning repo reproduction. Use when the task is specifically to capture or normalize evidence from the selected smoke test or documented inference or evaluation SkillsMay 2026
- insforge-debugUse when diagnosing problems in an InsForge project — reactive failures (SDK error object, HTTP 4xx/5xx, gateway timeout 502/503/504, edge function failure or timeout, login/OAuth/auth errors, RLS denSkillsJul 2026
