@edupia-tutor/spec-driven-docs 0.14.0

package/commands/report-bug.tmpl

@@ -0,0 +1,145 @@
+# /report-bug — File a Spec-Traced Bug (Tester & QC-Facing)
+
+For **testers and QC** — including **product-gaps** surfaced by the `/qc-*` pipeline
+(`/qc-run-test` FAIL classified product-gap, or a `DOC_GAPS` spec-defect blocker from
+`/qc-analyze`). Produces a structured bug report with full spec context, classifies the likely
+layer, and saves it for handoff to the dev team.
+
+**READ-ONLY on specs and code.** This command never edits PRD, BDD, tech-docs, or source.
+Fixing is the dev's job (`/fix-bug`); writing scenarios is `/propose-scenario`.
+
+Usage: `/report-bug {UC-ID or TICKET} {short description}`
+Example: `/report-bug FT-001 account locks after 6 failed logins, spec says 5`
+
+## Gate
+{{include:steps/gate.md}}
+
+*Note: For this command, the target in Step 1 is a UC-ID / TICKET from `$ARGUMENTS`. Resolve the matching `.feature` file if one exists; if not, continue — a bug can still be filed.*
+
+## Context
+{{include:steps/context-loader.md}}
+
+---
+
+## Step 1 — Resolve Spec Context
+
+Locate the spec chain for the bug's UC/TICKET. Prefer `spec-manifest.yaml` (umbrella/tester setup) if present; else use resolved `paths`.
+
+Gather and store:
+- `prd_path` + current PRD `Version`
+- `bdd_path` (the `.feature` for this UC) + the specific **failing scenario** title, if one matches
+- `tech_doc_path` (if any)
+- `service` / domain
+
+If no `.feature` scenario matches the reported behavior → set `coverage_gap = true` (the behavior is untested by BDD).
+
+## Step 2 — Gather Bug Details
+
+If not already in `$ARGUMENTS`, ask the tester (one compact prompt):
+
+```
+File a bug — answer what you can:
+  1. Where does it occur? (endpoint / screen / flow)
+  2. Steps to reproduce?
+  3. Expected (per spec) vs Actual?
+  4. Error / log / status code?
+  5. Environment? (staging / prod / local)
+```
+
+## Step 3 — Identify the AC Violated
+
+Read the PRD acceptance criteria for this UC. Match the bug to the specific **AC** it violates
+(e.g. `AC3: "5 failed logins → lock 30m"`). Quote it verbatim. If the behavior maps to no AC →
+note "No AC covers this" and treat as a possible PRD gap.
+
+## Step 4 — Classify Likely Layer (BUG_FLOW)
+
+Apply the BUG_FLOW decision table to suggest where the root cause likely is — this routes the bug:
+
+| If… | Likely layer | Route to |
+|------|-------------|----------|
+| Code contradicts a BDD scenario | **Code bug** (Case 1) | Dev → `/fix-bug` |
+| BDD scenario contradicts PRD AC | **BDD bug** (Case 2) | Dev/PO fix BDD |
+| PRD AC is ambiguous / silent | **PRD ambiguity** (Case 3) | PO clarifies PRD |
+| Behavior correct but **no scenario covers it** | **BDD coverage gap** | Tester → `/propose-scenario` |
+| UI ≠ Design Spec | **Design Spec bug** (Case 5) | Dev/Designer |
+| Env / data only | **Environment** (Case 6) | DevOps |
+
+State the classification as a suggestion (dev confirms during `/fix-bug`).
+
+## Step 5 — Write the Report
+
+Assign `BUG-{today YYYYMMDD}-{NN}` (NN = next sequence among existing reports).
+Write to `{paths.bug_reports_dir}/{BUG-ID}.md` (resolved to `{spec_source}/feedback/bug-reports/` in umbrella mode; create dir if needed) using the structure in the Output block, and also print it for pasting into Jira/Slack.
+
+## Step 5.5 — Backfill the trace (pending-view link)
+
+If Step 1 matched a specific failing scenario `{UC-ID}-SC{N}` **and** a trace row exists in
+`{paths.trace_dir}/{domain}/{prd-slug}/{UC-ID}.tsv`, update **only** that row so the PO/PM "waiting-on" view points
+to this bug — leave every other column (incl. `qc_status`) unchanged:
+- `qc_blocked_by` = `{BUG-ID}`
+- `qc_owner` = `dev` if likely layer ∈ {Code, BDD, Design Spec, Env} · `po` if likely layer = PRD ambiguity
+
+Skip silently if no SC matched or no trace file/row exists (a bug can still be filed). This is
+the only write this command makes to operational state — it still **never** edits PRD/BDD/code.
+
+## Step 6 — Handoff (so PO/Dev actually see it)
+
+The report only reaches PO/Dev if it is **committed and pushed to the shared spec repo**. A local file is a dead drop.
+
+Determine the repo that owns `{paths.bug_reports_dir}`:
+- Umbrella mode → the spec submodule at `{spec_source}`
+- Single-service → the current repo
+
+Then commit + push **that** repo:
+
+```bash
+cd {spec_source}              # umbrella: the spec submodule; single-service: omit
+git add feedback/bug-reports/{BUG-ID}.md
+git commit -m "qa(bug): {BUG-ID} — {short description}"
+git push                      # → PO/Dev see it on their next /sync
+```
+
+- If the tester lacks push rights to the spec repo → open a PR / MR instead, or hand the file to whoever owns it. Print this fallback.
+- Print the exact commands if you do not run them automatically.
+
+> PO/Dev are notified through their normal routine: `/sync` lists newly-pulled bug reports.
+
+---
+
+## Output
+
+{{include:steps/report-footer.md}}
+
+```
+🐞 {BUG-ID}  →  {paths.bug_reports_dir}/{BUG-ID}.md  (in shared spec repo)
+
+Feature  : {UC-ID} — {feature name}   |  Service: {service}   |  Severity: {Critical|Major|Minor}
+State    : 🟢 Open   (lifecycle: Open → Fixed → Closed — set `Fixed` by /fix-bug, `Closed` after /qc-run-test re-verify pass)
+
+Spec context
+  PRD      : {prd_path} (v{prd_version})
+  BDD      : {bdd_path} → Scenario: "{scenario title}"   {or: ⚠️ no scenario covers this}
+  Tech Doc : {tech_doc_path}
+
+AC violated
+  {AC-N}: "{AC text}"
+
+Expected (per spec) : {expected}
+Actual              : {actual}
+Steps to reproduce  : {1..N}
+Environment         : {env}
+
+Likely layer : {Code | BDD | PRD | Design Spec | Env}  →  {route}
+
+Handoff : {✅ committed + pushed to spec repo | ⚠️ run the git commands above / open a PR}
+
+---
+Status : ✅ Complete (read-only on specs/code — only wrote the feedback file)
+Output Artifacts: created {paths.bug_reports_dir}/{BUG-ID}.md (pushed to shared spec repo)
+Next   :
+  - PO/Dev will see this on their next /sync
+  - Code bug      → dev runs /fix-bug {BUG-ID}
+  - PRD ambiguity → PO (BUG_FLOW Case 3)
+  - Coverage gap  → /propose-scenario {UC-ID}
+```