@edupia-tutor/spec-driven-docs 0.14.0

package/commands/fix-bug.tmpl

@@ -0,0 +1,171 @@
+# /fix-bug — Full Bug Fix Workflow
+
+## Gate
+{{include:steps/gate.md}}
+
+*Note: For this command, the target in Step 1 is a ticket ID (e.g., `PROJ-123`), a **filed bug `{BUG-ID}`** (a `{paths.bug_reports_dir}/{BUG-ID}.md` from `/report-bug` — e.g. a QC product-gap), or a bug description from `$ARGUMENTS`. If a `{BUG-ID}` is given, resolve & read that report for spec context; otherwise proceed to context loading.*
+
+## Context
+{{include:steps/context-loader.md}}
+
+---
+
+## Phase 1 — Gather Info
+If a `{BUG-ID}` was given: read `{paths.bug_reports_dir}/{BUG-ID}.md` for the spec context, AC violated, expected-vs-actual, and the suggested layer — use it as the bug details (no need to re-ask).
+If ticket: fetch details (or ask user to paste).
+If no ticket / BUG-ID — CHECKPOINT:
+1. Where does the bug occur? (module, endpoint, flow)
+2. Steps to reproduce?
+3. Expected vs Actual?
+4. Error log / stack trace?
+
+## Phase 2 — Root Cause Analysis
+
+Use `active_module` from context to select the relevant table.
+
+### If `platform_type = backend`
+
+#### java-spring / golang / dotnet / php-laravel
+
+| Bug Type | Common Location | How to Check |
+|----------|----------------|--------------|
+| Wrong response data | Mapping layer | Check field mapping, DTO conversions |
+| 400 Bad Request | Input validation | Check DTO constraints / validators |
+| 401 Unauthorized | Auth filter | Check token config, filter order |
+| 403 Forbidden | Auth config | Check role-based access rules |
+| 404 Not Found | Repository query | Check find method, ID types |
+| N+1 Query | Data access | Check for missing JOIN FETCH / eager load |
+| Null Pointer | Optional not handled | Check Optional.orElseThrow, null guards |
+| Transaction rollback | Missing @Transactional | Check transaction scope, propagation |
+| Stale cache | Missing eviction | Check cache invalidation triggers |
+| Type mismatch | Filter / specification | Check field types in predicates |
+
+#### context-engineering (AI/LLM pipelines)
+
+| Bug Type | Common Location | How to Check |
+|----------|----------------|--------------|
+| Wrong pipeline output | Prompt template | Check prompt content; verify variables are substituted correctly |
+| Missing context in output | Context assembly | Verify all required context blocks are included and non-empty |
+| Schema validation failure | Output parser | Compare raw LLM output vs expected schema; add stricter output instructions |
+| Flaky / non-deterministic results | LLM temperature | Check temperature setting; use fixed seed/mock in tests |
+| API rate limit errors | LLM client | Implement backoff; check quota usage in provider dashboard |
+| Token limit exceeded | Prompt assembly | Reduce context size; add chunking strategy |
+
+### If `platform_type = web-frontend`
+
+| Bug Type | Common Location | How to Check |
+|----------|----------------|--------------|
+| Wrong data displayed | State / store | Check state update logic, selector |
+| UI not re-rendering | Missing reactive dep | Check deps array, state immutability |
+| API data not loading | HTTP client / hook | Check network tab, error handler |
+| 401 on API call | Auth token | Check token refresh, header injection |
+| Form not submitting | Validation / handler | Check form state, required fields, errors |
+| Route not found | Router config | Check route definition, lazy import |
+| Build / type error | TypeScript types | Compare type definitions vs actual API shape |
+
+### If `platform_type = mobile`
+
+| Bug Type | Common Location | How to Check |
+|----------|----------------|--------------|
+| Screen shows stale data | State / BLoC / ViewModel | Check event dispatched, state emitted correctly |
+| Crash on navigation | Route param missing | Check params passed, null safety |
+| API call not firing | Repository / service layer | Add log in repo method, check network |
+| UI not reflecting state | Widget not observing stream | Check `BlocBuilder` / `StateObserver` setup |
+| Crash on app resume | Lifecycle handler | Check `onResume` / `viewDidAppear` logic |
+| Auth token expired | Token refresh logic | Check refresh flow, token storage |
+| Permission denied | OS permission | Check runtime permission request code |
+
+CHECKPOINT — Root Cause Report:
+```
+Bug: {description} | Module: {name}
+Root cause: {analysis}
+Affected files: {list}
+Proposed fix: {what to change}
+Regression risk: Low / Medium / High
+Proceed? (Y/N)
+```
+
+## Phase 3 — Fix
+
+*Umbrella mode: the buggy code lives in the **service submodule** resolved at context-loader Step 1.6 — create the branch and run every git/build step from **inside** `{service_root}`. Single-service: omit the `cd`.*
+
+```bash
+cd {service_root}                              # umbrella: the service submodule; single-service: omit
+git checkout -b fix/{TICKET_ID}-{description}
+```
+Apply fix. Add trace annotation if file has `@trace.implements`:
+```
+@trace.fixes={TICKET_ID}
+@trace.root_cause={brief description}
+```
+
+## Phase 4 — Regression Test
+```
+// @trace.verifies={UC-ID}
+// @trace.regression={TICKET_ID}
+Test: "Regression {TICKET_ID}: {bug description}"
+```
+Run test. If fail → debug and fix (max 3 iterations).
+
+## Phase 5 — Build & Commit (2-layer push in umbrella mode)
+```bash
+{conventions.build_command}   # max 3 retries — runs inside {service_root} in umbrella mode
+# Tầng 1 — push the fix branch in the service submodule (where the code lives):
+git add {files}
+git commit -m "fix({TICKET_ID}): {description}"
+git push -u origin fix/{TICKET_ID}-{slug}      # then open a PR into the service's tracked branch
+```
+> **Umbrella mode — Tầng 2 (bump umbrella pointer):** the umbrella records a *commit* of the service
+> submodule, not a branch. After the fix-branch PR **merges** into the service's tracked branch, bump
+> the pointer so teammates pulling the umbrella don't hit "commit not found":
+> ```bash
+> cd -                                          # back to umbrella root
+> git add {service_root} && git commit -m "chore: bump {service_root} pointer (fix {TICKET_ID})"
+> git push
+> ```
+> Single-service mode: no umbrella pointer — Tầng 1 is the whole push. Full rule: Sync & Update §4.4 (commit 2 tầng).
+
+## Phase 5.5 — Close the bug report (if fixing a filed `{BUG-ID}`)
+
+*Skip if the target was a plain ticket/description (no `{BUG-ID}` file).*
+
+After the fix is committed, update `{paths.bug_reports_dir}/{BUG-ID}.md`:
+- Set `State` → `🟡 Fixed` and append a short **Resolution** (root cause + commit/PR link).
+- It is **not** `Closed` yet — QC owns verification: when `/qc-run-test` re-runs and `qc_status`
+  for the linked SC flips to `pass`, it becomes `🟢 Closed` (and `qc_owner`/`qc_blocked_by` clear).
+- Commit the updated report to the spec repo (same 2-layer push as `/report-bug`) so the PO/PM
+  "waiting-on" view reflects it on `/sync`.
+
+This is the only write `/fix-bug` makes to the feedback area — it still fixes **code** only,
+never edits PRD/BDD (spec changes are PO/Dev per BUG_FLOW Case 2–4).
+
+## Phase 6 — Offer to Record a Lesson (optional)
+
+If the root cause was a **mistake the AI made during generation and could repeat**
+(e.g. it generated code that skipped a layer, missed a null guard, used a wrong pattern —
+NOT an external cause like a third-party outage or bad input data), ask:
+
+```
+This root cause looks like a repeatable AI mistake.
+Record it as a project lesson so it isn't generated again? (Y/N)
+```
+
+If `Y` → run the capture procedure below with `source=/fix-bug {TICKET_ID}`, an appropriate
+`category` (usually `code-gen`), and `scope` = the affected domain or file glob.
+
+{{include:steps/capture-lesson.md}}
+
+## Output
+
+{{include:steps/report-footer.md}}
+
+```
+/fix-bug Complete — {TICKET_ID}
+Root Cause: {analysis}
+Changes: {list}
+✅ Regression test added | ✅ Build: SUCCESS
+{🐞 BUG-{id} → State: Fixed (pushed) — Closed after /qc-run-test re-verify pass | if fixing a filed bug}
+{📝 Lesson L-NNN recorded (if captured)}
+Branch: fix/{TICKET_ID}-{slug}
+Next: Create PR and link to ticket. {QC: re-run /qc-run-test {UC-ID} to verify + close the bug | if applicable}
+```