@edupia-tutor/spec-driven-docs 0.14.0

package/commands/review-context.tmpl

@@ -0,0 +1,415 @@
+# /review-context — Review PRD or BDD for Quality & Consistency
+
+**READ-ONLY analysis mode — writes a findings file, does NOT modify the target.**
+**Use `--resume` to apply accepted findings.**
+
+## Gate
+{{include:steps/gate.md}}
+
+*Note: For this command, the target in Step 1 is either a `.md` PRD file or a `.feature` BDD file.
+If the path is a `prd.md` under `{paths.specs_dir}/{domain}/{prd-slug}/` → PRD Review Mode.
+If the path ends with `.feature` → BDD Review Mode.
+If `$ARGUMENTS` contains `--resume` → skip to Resume Mode below.
+If `$ARGUMENTS` contains `--fix` → skip to Fix Mode below (apply all auto-fixable findings immediately).*
+
+## Context
+{{include:steps/context-loader.md}}
+
+---
+
+## Detect Review Mode
+
+After resolving the target file:
+- `.feature` file → **BDD Review Mode** (jump to BDD section)
+- `prd.md` under `{paths.specs_dir}/*/*/` → **PRD Review Mode** (continue below)
+- Unknown → ask: "Is this a PRD file or a BDD feature file? (prd/bdd)"
+
+Also check flags:
+- `--fix` present → after running all checks, apply `auto_fixable: true` findings immediately (skip Review Board)
+- `--resume` present → skip analysis entirely, go to Resume Mode
+
+Derive the output findings filename:
+- PRD: `{paths.refinement_dir}/{prd-slug}-review-context-findings.yaml`
+- BDD: `{paths.refinement_dir}/{uc-id}-review-bdd-findings.yaml`
+
+---
+
+## Review Procedure
+{{include:steps/review-fanout.md}}
+
+**How the checks below map onto the procedure:**
+- **DIMENSIONS** = the check groups for the detected mode — PRD: `P1, P2, P4, P5`; BDD: `B1, B2, B3, B4, B5, B6`. Fan out one sub-agent per check group, each scanning the full target file for just that group.
+- **Orchestrator-run checks (not fanned out):** `P0` (umbrella routing) and `P3` (cross-PRD conflict) need config / other-PRD context — the orchestrator runs these itself **before** the fan-out and adds their results to `ALL_FINDINGS`.
+- The completeness-critic loop (Phase 2) guarantees the findings file is complete in one run — re-running `/review-context` should surface **0 new** findings. Map each dimension into the `check_id` field of the schema below.
+
+---
+
+## PRD Review Mode
+
+### P0 — Umbrella Routing Check (umbrella mode only)
+
+*Skip this check entirely if `setup.mode` is not `"umbrella"` (i.e., `services` section absent from project-context.yaml).*
+
+When `setup.mode = umbrella`, the PRD must have correct routing metadata so context-loader Step 1.5 can direct generated output to the right service submodule. Run these checks **before P1–P5**:
+
+**P0.1 — `@trace.domain` presence**
+- Read the PRD frontmatter block (lines starting with `@trace.` at top of file)
+- If `@trace.domain` is **absent** → **critical** finding:
+  - `finding`: "`@trace.domain` is missing. Dev team's umbrella routing depends on this field to route BDD and code output to the correct service submodule."
+  - `suggestion`: "Add `@trace.domain: {domain}` to the PRD frontmatter. Use one of the domain keys defined in the umbrella's `project-context.yaml` services section."
+  - `auto_fixable: false` — PO must confirm the correct domain name
+
+**P0.2 — `@trace.domain` matches a service key**
+- If `@trace.domain` is present, check if its value matches any key in the `services` section of project-context.yaml
+- If **no match found** → **critical** finding:
+  - `finding`: "`@trace.domain: {value}` does not match any key in the umbrella's `services` config. Routing will fall back to default paths and BDD may be generated to the wrong location."
+  - `suggestion`: "Either update `@trace.domain` to match an existing service key ({list known keys}), or add a new entry to `services` in project-context.yaml for domain `{value}`."
+  - `auto_fixable: false`
+- If `services` section is not yet configured (empty/placeholder) → **major** finding:
+  - `finding`: "Umbrella `services` section is not yet configured. Cannot verify domain routing."
+  - `suggestion`: "Update `.agent/project-context.yaml` services section with domain-to-submodule mapping before generating BDD."
+  - `auto_fixable: false`
+
+**P0.3 — `@trace.status` check**
+- If `@trace.status` is absent → **minor**, `auto_fixable: true` (add `@trace.status: draft`)
+- If `@trace.status: draft` → **major**, `auto_fixable: false`:
+  - `finding`: "PRD status is `draft`. Dev team should not generate BDD from an unapproved PRD."
+  - `suggestion`: "PO/SA should review and update status to `approved` before dev team proceeds."
+
+> **P0 is a gate check:** If P0.1 or P0.2 yields a critical finding, display a warning before proceeding:
+> ```
+> ⚠️  ROUTING WARNING: @trace.domain issue detected.
+>    BDD/code generated from this PRD may land in the wrong service submodule.
+>    Resolve P0 findings before running /generate-bdd.
+> ```
+> Then continue with P1–P5 (do not abort — PO may be reviewing early-stage PRDs).
+
+### P1 — Terminology Check (Business Dictionary)
+
+Load `{paths.business_dictionary}`.
+Scan the entire PRD for terminology issues:
+
+1. **Banned terms** — every occurrence of a term in §Banned Terms:
+   → Severity: **critical**. AI can auto-fix in `--resume`.
+
+2. **Inconsistent usage** — same concept named differently across sections:
+   → Severity: **major**. Flag both occurrences. Human decides canonical form in Review Board note.
+
+3. **Unlisted business terms** — important terms absent from the dictionary:
+   → Severity: **minor**. Suggest adding to `business-dictionary.md`.
+
+### P2 — Ambiguity Check
+
+Scan each AC and BR for:
+
+| Signal | Example | Severity |
+|--------|---------|----------|
+| Vague quantifier | "fast", "large", "reasonable", "quickly" | Critical |
+| Missing actor | "the system should" with no trigger specified | Major |
+| Undefined reference | "{SomeThing}" used but never defined in this PRD | Major |
+| Missing negative path | AC only describes happy path but BR has error conditions | Minor |
+| Passive voice hiding actor | "Invoice is created" — who creates it? | Minor |
+
+→ AI cannot auto-fix P2 findings. Human must write the fix in Review Board "Modify" note.
+
+### P3 — Domain Conflict Check
+
+List all other PRDs in `{paths.specs_dir}/{domain}/*/prd.md`.
+For each one, check if this PRD contradicts a defined BR (same trigger, different outcome)
+or redefines an entity field/status transition differently.
+
+→ Severity: **critical**. Human decides which PRD is correct. Note required.
+
+### P4 — Structural Completeness
+
+- [ ] Metadata block: Version, Author, Date, Status
+- [ ] At least 1 UC with `#### {TICKET-ID}-UC{N}:` heading
+- [ ] Each UC has: Description, Actors, Preconditions, Acceptance Criteria, Business Rules
+- [ ] `## Changelog` section exists
+- [ ] No `{{PLACEHOLDER}}` values unfilled
+
+→ Missing sections: **major**. AI can add skeleton in `--resume` if accepted.
+
+### P5 — Custom Criteria (optional)
+
+If `$ARGUMENTS` contains additional criteria after the file path, evaluate them and create
+findings with `check_id: "P5"` and severity as appropriate.
+
+---
+
+## BDD Review Mode
+
+### B1 — PRD Coverage Check
+
+Load the PRD referenced by `# @trace.prd:` in the feature file header.
+Map every AC and every BR (including sub-bullets) to scenarios:
+
+```
+AC1 ({short text}) → SC1, SC2  ✅
+AC2 ({short text}) → MISSING   ❌
+BR1 ({short text}) → SC1       ✅
+BR2 ({short text}) → MISSING   ❌
+```
+
+→ Each missing AC/BR coverage: **critical** finding.
+   If accepted in Review Board, `--resume` generates the missing scenario(s).
+
+### B2 — Terminology & Entity Check
+
+Using `{paths.business_dictionary}` and `{paths.core_entities}`:
+
+1. **Banned terms in steps** → **critical**, auto-fixable in `--resume`
+2. **Non-canonical entity names** → **major**, auto-fixable
+3. **Non-canonical field names in data tables** → **major**, auto-fixable
+4. **Technically-looking sample data** (UUIDs, `item_123`) → **minor**, auto-fixable
+
+### B3 — Gherkin Rules Check (R1–R10)
+
+| Rule | Check | Auto-fixable? |
+|------|-------|---------------|
+| R1 | Every scenario has Given + When + Then | No — needs scenario redesign |
+| R2 | No chained `When … Then … When` | No — needs redesign |
+| R3 | No UI selectors / API paths / tech terms in steps | Yes — replace with business phrasing |
+| R4 | Scenario name is a business outcome | No — needs human rename |
+| R5 | Declarative WHAT, not imperative HOW | No — needs rewrite |
+| R6 | `Then` asserts observable business outcome | No — needs redesign |
+| R7 | Concrete values, not "valid data" | Yes — substitute realistic values |
+| R8 | Each scenario is independently runnable | No — needs redesign |
+| R9 | Data tables have enough columns for Then | Yes — add missing columns |
+| R10 | Cross-UC reference uses navigation phrasing + Note | Yes — add Note comment |
+
+→ R3, R7, R9, R10 violations: auto-fixable. Others require human guidance via Review Board note.
+
+### B4 — Compliance Checks (C.1–C.5)
+
+- [ ] C.1 Wireframe Coverage: every screen component/action has ≥1 SC → finding per missing item
+- [ ] C.2 PRD Traceability: covered fully by B1 — do NOT create new findings here; deduplicate against B1 findings
+- [ ] C.3 Business Dictionary terms used → same as B2
+- [ ] C.4 Banned Terms: 0 banned terms → **critical**, auto-fixable
+- [ ] C.5 NHÓM Grouping: if ≥3 SCs, grouped by business theme → **major**, auto-fixable
+
+### B5 — Metadata & Structural Check
+
+- [ ] File header has all required `@trace.*` fields — check each explicitly: `@trace.id`, `@trace.title`, `@trace.revision`, `@trace.domain`, `@trace.service`, `@trace.module`, `@trace.status`, `@trace.author`, `@trace.created_at`, `@trace.prd`, `@trace.prd_version`, `@trace.bdd_version`, `@trace.business_rules`, `@trace.dataset` → **minor** per missing field, auto-fixable
+  - Note: `@trace.revision` is always `1` (static field — see generate-bdd.tmpl). Only check for presence; do NOT flag value as stale.
+- [ ] Every scenario has `# @trace.scenario`, `# @trace.sc_version`, `# @trace.business_rules`, `# Side-effects:` → **minor**, auto-fixable
+- [ ] Coverage Matrix at end of file → **major**, auto-fixable (AI regenerates)
+- [ ] Pre-merge Checklist at end of file → **minor**, auto-fixable
+
+### B6 — Side-effect Completeness
+
+For each `@happy` scenario:
+- `# Side-effects:` comment lists all observable side effects
+- `Then` block has `And <side-effect>` for each listed side effect
+
+→ Missing side-effect assertion: **major**, auto-fixable.
+
+---
+
+## Write Findings File
+
+After running all checks, write `{paths.refinement_dir}/{slug}-review-*-findings.yaml`:
+
+```yaml
+source_file: "{absolute path to reviewed file}"
+generated_at: "{ISO datetime}"
+review_type: "{prd | bdd}"
+status: "pending_review"
+
+findings:
+  - id: "F001"
+    check_id: "P1"           # P1-P5 for PRD; B1-B6 for BDD
+    severity: "critical"     # critical | major | minor
+    section: "{section or scenario ID where issue was found}"
+    uc_id: "{UC-ID this finding belongs to — PRD: the UC heading; BDD: @trace.id; \"\" if global}"
+    quote: "{verbatim snippet copied EXACTLY from the reviewed file at the issue location, ≤120 chars}"
+    finding: "{clear description of the issue}"
+    suggestion: "{specific actionable fix — AI will apply this in --resume if accepted}"
+    auto_fixable: true       # true = AI can apply; false = human must write note in Review Board
+    status: "pending"        # pending | accepted | modified | rejected | deferred
+
+summary:
+  total_findings: {N}
+  by_severity: { critical: {N}, major: {N}, minor: {N} }
+  auto_fixable: {N}
+  requires_human_decision: {N}
+  recommendation: "APPROVED | 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 reviewed file 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 (`@trace.id` for BDD, the UC heading for PRD; `""` if global).
+> These let a reviewer click a finding in the Review Board and jump to the precise source location.
+
+## Post-Analysis Routing
+
+After running all checks and writing the findings file:
+
+**If `--fix` flag present** → jump to Fix Mode (apply `auto_fixable: true` findings immediately).
+
+**If no flag** → print Report below and stop.
+
+## Report
+
+{{include:steps/report-footer.md}}
+
+```
+/review-context Complete — {target file}
+Mode: {PRD | BDD}
+Findings: {total} | 🔴 Critical: {N} | 🟡 Major: {N} | 🟢 Minor: {N}
+Auto-fixable: {N} | Needs human decision: {N}
+
+Findings file:
+  {If PRD}: {paths.refinement_dir}/{prd-slug}-review-context-findings.yaml
+  {If BDD}: {paths.refinement_dir}/{uc-id}-review-bdd-findings.yaml
+
+Next options:
+  A) Quick fix  : /review-context --fix {target-file}
+                  → applies all auto-fixable findings immediately
+  B) Review Board: open findings file → accept/modify/reject
+                  → /review-context --resume {target-file}
+```
+
+---
+
+## Fix Mode — Apply Auto-Fixable Findings Immediately
+
+*Triggered when `$ARGUMENTS` contains `--fix`.*
+*Example: `/review-context --fix specs/payment/process-payment/bdd/PAY-001.feature`*
+
+This mode runs the full analysis (same as default), then immediately applies every
+`auto_fixable: true` finding without going through the Review Board.
+
+Use for: BDD cleanup, terminology fixes, metadata gaps — anything the AI can safely
+correct without a human judgment call. Findings requiring human decisions are written
+to the findings file as usual and left `status: pending`.
+
+### Phase 1 — Run analysis
+
+Run all checks via the **Review Procedure** (fan-out + completeness loop) exactly as in the default mode.
+Write the findings file with all `status: "pending"` as usual.
+
+### Phase 2 — Apply auto-fixable findings
+
+For each finding where `auto_fixable: true`, in order (critical → major → minor):
+
+**For PRD files:**
+
+| check_id | What to apply |
+|----------|--------------|
+| P0.3 (Missing status) | Add `@trace.status: draft` to frontmatter |
+| P1 (Banned term) | Replace every banned term occurrence with canonical term |
+| P4 (Structure) | Add missing section/metadata skeleton |
+
+**For BDD files:**
+
+| check_id | What to apply |
+|----------|--------------|
+| B2 (Terminology) | Replace banned terms, fix entity/field names, fix technical sample data |
+| B3 R3 | Replace tech terms/UI selectors with business phrasing |
+| B3 R7 | Substitute concrete realistic values |
+| B3 R9 | Add missing data table columns |
+| B3 R10 | Add cross-UC navigation Note comment |
+| B4 C4 | Fix banned terms in tags |
+| B4 C5 | Add NHÓM grouping if ≥3 SCs |
+| B5 | Add missing @trace headers, regenerate Coverage Matrix / Pre-merge Checklist |
+| B6 | Add missing `And <side-effect>` to Then blocks |
+
+After applying each finding, mark it `status: "applied_automatically"` in the findings file.
+
+### Phase 3 — Version bump
+
+- **PRD**: if ≥1 finding applied → bump **minor** version (auto-fix only applies P1 banned-term replacements and P4 skeleton additions — never alters UC structure or BR content, so minor bump is always correct), add Changelog entry:
+  `Auto-fix: applied {N} auto-fixable review-context findings`
+- **BDD**: if ≥1 finding applied → increment `@trace.bdd_version` by 0.1
+
+### Phase 4 — Report
+
+```
+/review-context --fix Applied — {target file}
+Mode: {PRD | BDD}
+
+Auto-fixed : {N} findings ({critical} critical, {major} major, {minor} minor)
+  - {change 1 summary}
+  - {change 2 summary}
+
+Still pending (needs human decision): {N}
+  - F00X [{severity}] {finding summary}  ← open findings file in Review Board
+
+{If PRD}: Version bumped: {old} → {new}
+{If BDD}: bdd_version: {old} → {new}
+
+Findings file:
+  {If PRD}: {paths.refinement_dir}/{prd-slug}-review-context-findings.yaml
+  {If BDD}: {paths.refinement_dir}/{uc-id}-review-bdd-findings.yaml
+Re-run /review-context {file} to confirm 0 remaining critical findings.
+```
+
+If 0 findings were auto-fixable → print:
+```
+Nothing to auto-fix. All {N} findings require human decision.
+Open findings file in Review Board → then run: /review-context --resume {file}
+```
+
+---
+
+## Resume Mode — Apply Accepted Findings
+
+*Triggered when `$ARGUMENTS` contains `--resume`.*
+*Example: `/review-context --resume specs/payment/process-payment/prd.md`*
+
+### Phase 1 — Read accepted findings
+
+1. Derive findings filename from target file using the same rule as Detect Review Mode:
+   - PRD: `{paths.refinement_dir}/{prd-slug}-review-context-findings.yaml`
+   - BDD: `{paths.refinement_dir}/{uc-id}-review-bdd-findings.yaml`
+2. Read the findings file.
+3. Collect findings where `status: "accepted"` or `status: "modified"`.
+4. If none → report "No accepted findings. File unchanged." and stop.
+
+### Phase 2 — Apply fixes
+
+Apply in order: critical → major → minor.
+
+**For PRD findings:**
+| check_id | What to do |
+|----------|-----------|
+| P0.3 (Missing status) | Add `@trace.status: draft` to frontmatter |
+| P1 (Banned term) | Replace every occurrence of banned term with canonical term |
+| P2 (Ambiguity) | Apply the fix stated in `suggestion` or `modified` note |
+| P3 (Conflict) | Apply the resolution stated in the modified note |
+| P4 (Structure) | Add the missing section/metadata field |
+| P5 (Custom) | Apply as stated in suggestion/note |
+
+→ After applying, bump PRD version (minor) and add Changelog entry.
+
+**For BDD findings:**
+| check_id | What to do |
+|----------|-----------|
+| B1 (Coverage gap) | Generate new scenario(s) for the uncovered AC/BR and insert into correct NHÓM |
+| B2 (Terminology) | Replace banned terms, fix entity/field names |
+| B3 (Gherkin rule) | Apply rule-specific fix (replace tech terms, add concrete values, etc.) |
+| B4 (Compliance) | Add NHÓM grouping, fix @trace tags |
+| B5 (Metadata) | Add missing @trace headers, regenerate Coverage Matrix / Pre-merge Checklist |
+| B6 (Side effects) | Add missing `And <side-effect>` to Then block |
+
+→ After applying, increment `@trace.bdd_version` in file header by 0.1.
+→ Also update `{paths.trace_dir}/{domain}/{prd-slug}/{UC-ID}.tsv`: set `bdd_version` column to the new `@trace.bdd_version` value for all rows, and set `last_updated` to today's date.
+
+### Phase 3 — Report
+
+```
+/review-context --resume Applied — {target file}
+Applied  : {N} findings ({critical} critical, {major} major, {minor} minor)
+Skipped  : {N} rejected/deferred
+
+Changes:
+  - {change 1 summary}
+  - {change 2 summary}
+
+{If PRD}: Version bumped: {old} → {new}
+{If BDD}: bdd_version: {old} → {new}
+
+Re-run /review-context {file} to confirm 0 remaining critical findings.
+```