@edupia-tutor/spec-driven-docs 0.14.0

package/commands/propose-scenario.tmpl

@@ -0,0 +1,129 @@
+# /propose-scenario — Propose a New BDD Scenario (Tester & QC-Facing)
+
+For **testers and QC** who discover an edge case not covered by existing BDD (e.g. a `DOC_GAPS`
+missing-coverage gap from `/qc-analyze`). Drafts a Gherkin scenario into a **proposals area** for
+PO/Dev to review and promote.
+
+**Does NOT edit the canonical `.feature` file.** BDD is owned by PO/Dev — this command only writes
+a proposal. Promotion into the real BDD is a PO/Dev action.
+
+Usage: `/propose-scenario {UC-ID} {edge case description}`
+Example: `/propose-scenario FT-001 login with email that has trailing spaces should still succeed`
+
+## Gate
+{{include:steps/gate.md}}
+
+*Note: For this command, the target in Step 1 is a UC-ID from `$ARGUMENTS`. Resolve its `.feature` file (for vocabulary + existing scenarios) and its PRD.*
+
+## Context
+{{include:steps/context-loader.md}}
+
+---
+
+## Step 1 — Resolve UC + Platform
+
+Locate (via `spec-manifest.yaml` if present, else `paths`):
+- `prd_path` + the UC's acceptance criteria list
+- `bdd_path` + `active_platform` (web / app / system) — to match scenario vocabulary and `@trace` tags
+- existing scenario titles for this UC (to avoid proposing a duplicate)
+
+## Step 2 — Coverage Decision (CRITICAL)
+
+A BDD scenario must trace to a PRD acceptance criterion. Determine which case applies:
+
+**Case A — behavior IS within an existing AC** (the AC implies it, BDD just lacks a scenario):
+→ This is a coverage gap. Proceed to draft the scenario (Step 3), mapped to that AC.
+
+**Case B — behavior is NOT in any AC** (genuinely new requirement):
+→ Do **not** draft a BDD proposal (a scenario would have nothing to trace to). Instead **write a
+PRD change request file** so the PO actually sees it on `/sync` (do not just print it):
+
+Write to `{paths.prd_change_requests_dir}/{UC-ID}-{slug}.md` (resolved to
+`{spec_source}/feedback/prd-change-requests/` in umbrella mode; create dir if needed):
+```
+# PRD Change Request — {UC-ID}: {short title}
+
+> ⚠️ New requirement found in test — NOT covered by any PRD AC (not a coverage gap).
+| Field | Value |
+|---|---|
+| UC / Ticket | {UC-ID} |
+| PRD | {prd_path} (v{prd_version}) |
+| Source | {BUG-ID if any | tester/QC observation} |
+| Requested by | tester/QC |
+| Status | Open |
+
+**Requested behavior:** {description}
+**Suggested AC (draft for PO):** "{draft AC text}"
+**Route to PO:** add/extend an AC in {prd_path} → `/refine-prd` → re-run `/generate-bdd` → dev `/generate-code`.
+```
+Then go to Step 5 (handoff applies to this file too). Skip Step 3–4 (no BDD scenario for Case B).
+
+If unsure which case → show the AC list and ask the tester which AC this maps to, or confirm it's new.
+
+## Step 3 — Draft the Scenario (Case A only)
+
+Write Gherkin consistent with `/generate-bdd` conventions for `active_platform`:
+- Use the platform vocabulary (web: clicks/sees; app: taps/sees; system: business events)
+- Include `@trace` tags: `@trace.uc={UC-ID}`, `@trace.ac={AC-N}`, plus `@proposed @from-test`
+- One focused scenario; concrete Given/When/Then; no implementation detail
+
+## Step 4 — Write the Proposal
+
+Write to `{paths.bdd_proposals_dir}/{UC-ID}-{slug}.md` (resolved to `{spec_source}/feedback/bdd-proposals/` in umbrella mode; create dir if needed).
+Do NOT touch the canonical `.feature`. The proposal doc contains the draft + review metadata
+(see Output). If the source was a bug, reference its `BUG-ID`.
+
+## Step 5 — Handoff (so PO/Dev actually see it)
+
+A proposal only reaches PO/Dev if it is **committed and pushed to the shared spec repo**.
+
+```bash
+cd {spec_source}              # umbrella: the spec submodule; single-service: omit
+git add feedback/bdd-proposals/{UC-ID}-{slug}.md
+git commit -m "qa(proposal): {UC-ID} — {title}"
+git push                      # → PO/Dev see it on their next /sync
+```
+
+- No push rights to the spec repo → open a PR / MR instead. Print this fallback.
+- For a **PRD change request** (Case B), commit the request file instead:
+  ```bash
+  cd {spec_source}
+  git add feedback/prd-change-requests/{UC-ID}-{slug}.md
+  git commit -m "qa(prd-change): {UC-ID} — {title}"
+  git push
+  ```
+
+> PO/Dev are notified through their normal routine: `/sync` lists newly-pulled proposals.
+
+---
+
+## Output
+
+{{include:steps/report-footer.md}}
+
+```
+📝 Scenario proposal → {paths.bdd_proposals_dir}/{UC-ID}-{slug}.md
+
+UC        : {UC-ID} ({active_platform})
+Maps to AC : {AC-N} — "{AC text}"
+Source     : {BUG-ID if any | tester observation}
+
+Proposed scenario (DRAFT — pending PO/Dev review):
+  @proposed @from-test @trace.uc={UC-ID} @trace.ac={AC-N}
+  Scenario: {title}
+    Given {…}
+    When  {…}
+    Then  {…}
+
+For PO/Dev to promote:
+  [ ] AC mapping correct? (or update PRD if requirement is actually new)
+  [ ] Add scenario to {bdd_path} (edit, or re-run /generate-bdd if PRD changed)
+  [ ] Then: /generate-code {UC-ID} + /dev-gen-test {UC-ID}
+
+Handoff : {✅ committed + pushed to spec repo | ⚠️ run git commands above / open a PR}
+
+---
+Status : ✅ Complete (read-only on canonical BDD — proposal only)
+Output Artifacts: created {paths.bdd_proposals_dir}/{UC-ID}-{slug}.md (pushed to shared spec repo)
+Next   : PO/Dev see it on their next /sync → review & promote
+```