@edupia-tutor/spec-driven-docs 0.14.0

package/commands/refine-prd.tmpl

@@ -0,0 +1,140 @@
+# /refine-prd — Analyze PRD Through 4 Review Lenses
+
+## Gate
+{{include:steps/gate.md}}
+
+*Note: For this command, the target file in Step 1 is a PRD file (`prd.md`) under `{paths.specs_dir}/{domain}/{prd-slug}/`. Read the full PRD after resolving the file.*
+
+## Context
+{{include:steps/context-loader.md}}
+
+---
+
+## Review Procedure
+{{include:steps/review-fanout.md}}
+
+---
+
+## Analyze — 4 Lenses (fan out over all four, then converge)
+
+Run the review through the **Review Procedure** above (`steps/review-fanout.md`).
+
+**DIMENSIONS** = the 4 lenses below — fan out one sub-agent per lens, each scanning the
+full PRD through its single lens:
+
+- **QA Lens**: Are ACs testable? Edge cases specified? Boundary conditions defined?
+- **DEV Lens**: Are API inputs/outputs clear? Business rules unambiguous? Cross-service deps fully described? Any technical risk?
+- **SA Lens**: Fits existing architecture? Security/auth implications? Data modeling clear?
+- **PO Lens**: Scope bounded? Priorities clear? Success metrics defined? Scope creep risk?
+
+The completeness-critic loop (Phase 2) is what guarantees the findings file is complete
+in one run — re-running `/refine-prd` should surface **0 new** findings. Map each
+dimension into the `lens` field of the schema below.
+
+## Output File
+
+Derive the output filename from the PRD slug:
+- PRD file: `{paths.specs_dir}/payment/create-invoice/prd.md` → output: `{paths.refinement_dir}/create-invoice-findings.yaml`
+- Rule: take the PRD's parent folder name (the prd-slug), append `-findings.yaml`
+
+Write `{paths.refinement_dir}/{prd-slug}-findings.yaml`:
+
+```yaml
+prd_source: "{paths.specs_dir}/{domain}/{prd-slug}/prd.md"
+generated_at: "{ISO datetime}"
+status: "pending_review"
+
+findings:
+  - id: "F001"
+    lens: "QA"           # QA | DEV | SA | PO
+    severity: "major"    # critical | major | minor
+    section: "§6. Acceptance Criteria"   # human-readable heading/section label
+    uc_id: "{TICKET-ID}-UC{N}"           # UC this finding belongs to; "" if PRD-global (scope, metrics, problem statement)
+    quote: "{verbatim snippet copied EXACTLY from the PRD at the issue location, ≤120 chars}"
+    finding: "{description of gap or issue}"
+    suggestion: "{specific actionable improvement}"
+    auto_fixable: false  # true = AI applies in --resume; false = human must write decision in note
+    status: "pending"    # pending | accepted | rejected | needs_discussion
+
+summary:
+  total_findings: {N}
+  by_severity: { critical: {N}, major: {N}, minor: {N} }
+  by_lens: { QA: {N}, DEV: {N}, SA: {N}, PO: {N} }
+  recommendation: "APPROVED_WITH_MINOR_CHANGES | NEEDS_REVISION | BLOCKED"
+```
+
+> **Locator fields (`quote` + `uc_id`) — required for Review Board source-jump.**
+> For every finding, copy a short **verbatim** `quote` straight from the PRD at the exact spot the
+> issue occurs — do NOT paraphrase; it is matched against the document to locate the line. Set
+> `uc_id` to the owning Use Case (or `""` for PRD-global findings). These let a reviewer click a
+> finding in the Review Board and jump straight to the precise location in the source PRD.
+
+## Report
+
+{{include:steps/report-footer.md}}
+
+```
+/refine-prd Complete — {PRD name}
+Findings: {total} | 🔴 Critical: {N} | 🟡 Major: {N} | 🟢 Minor: {N}
+Review: {paths.refinement_dir}/{prd-slug}-findings.yaml
+Next: Open in Review Board (right-click file) → Update PRD
+      → /review-context {prd-file}   ← verify PRD quality before generating BDD
+      → /generate-bdd {prd-file}
+```
+
+---
+
+## Resume Mode — Apply Findings & Bump Version
+
+*Triggered when `$ARGUMENTS` contains `--resume` (called by Review Board "Apply to PRD" button).*
+
+### Phase 1 — Read accepted findings
+
+1. Read `{paths.refinement_dir}/{prd-slug}-findings.yaml`.
+2. Collect all findings where `status: "accepted"` or `status: "modified"`.
+3. If no accepted findings → report "No accepted findings. PRD unchanged." and stop.
+
+### Phase 2 — Apply changes to PRD
+
+For each accepted finding, in order of severity (critical → major → minor):
+- Navigate to the PRD section indicated by `finding.section`.
+- Apply `finding.suggestion`. For `status: "modified"` findings, the human has already edited `finding.suggestion` in the Review Board — that edited value IS the fix to apply.
+- Do not alter any sections not referenced by an accepted finding.
+
+### Phase 2.5 — Update findings file
+
+For each finding that was applied (status was `accepted` or `modified`):
+- Set `status: "applied"` in `{paths.refinement_dir}/{prd-slug}-findings.yaml`.
+
+Update `summary.status: "applied"` in the findings file.
+
+### Phase 3 — Bump version & write changelog entry
+
+1. Read current `| **Version** |` value from PRD metadata table.
+2. Determine bump type from the set of accepted findings:
+   - **major** (X.0 → next X+1.0): new or removed Use Case, restructured scope, breaking BR change.
+   - **minor** (x.Y → x.Y+1): clarification, new edge case, AC/BR wording refinement.
+3. Compute new version string.
+4. Update PRD metadata:
+   - `| **Version** | {new_version} |`
+   - `| **Updated**  | {today YYYY-MM-DD} |`
+   - `| **Status**   | draft |` ← reset to draft, must be re-approved
+5. Prepend a new row to `## Changelog` at the bottom of the PRD:
+   ```
+   | {new_version} | {today} | {concise summary of all applied changes} |
+   ```
+
+### Phase 4 — Report
+
+```
+/refine-prd Applied — {PRD name}
+Version  : {old_version} → {new_version}
+Applied  : {N} findings ({critical} critical, {major} major, {minor} minor)
+Changes  :
+  - {change 1}
+  - {change 2}
+
+⚠️  BDD may be outdated. Run:
+    /review-context {prd-file}   ← verify PRD quality first
+    → /generate-bdd {prd-file}
+```