@edupia-tutor/spec-driven-docs 0.14.0

package/commands/review-tech-docs.tmpl

@@ -0,0 +1,317 @@
+# /review-tech-docs — Review Technical Design Document
+
+**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 a tech-design `.md` file in `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/`.
+If `$ARGUMENTS` contains `--resume` → skip to Resume Mode below.*
+
+## Context
+{{include:steps/context-loader.md}}
+
+---
+
+## Load Review Materials
+
+After loading base context, read the following in order:
+
+1. **Target tech-doc** — read fully. Extract from header:
+   - `@trace.id` → UC-ID
+   - `@trace.domain` → domain
+   - `@trace.prd` → source PRD ticket ID
+   - `@trace.status` → current status (draft / in-review / approved)
+
+2. **Source feature file** — load `{paths.specs_dir}/{domain}/{prd-slug}/bdd/{UC-ID}*.feature` if exists.
+
+3. **Other tech-docs in same domain** — list and load all `.md` files in
+   `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/` excluding the target. Used for conflict checking (T4).
+
+4. **Architecture reference** — re-confirm CLAUDE.md §2: layer order, architectural rules.
+
+5. **Core entities** — already loaded in context (Step 6 of context-loader).
+
+Derive findings filename:
+`{paths.refinement_dir}/{uc-id}-tech-review-findings.yaml`
+
+---
+
+## Review Dimensions
+
+### T1 — Architecture Alignment *(always CRITICAL if violated)*
+
+Cross-reference the proposed design against CLAUDE.md §2 rules:
+
+| Violation type | Severity |
+|----------------|----------|
+| Controller calls Repository directly (layer skip) | Critical |
+| Business logic in Controller or DTO | Critical |
+| Forbidden pattern from §3 | Critical |
+| Dependency going upstream (Service → Controller DTO) | Critical |
+| Transaction annotation on wrong layer | Major |
+| Missing separation (no Facade when arch requires it) | Major |
+
+For each finding:
+```
+Component: {class or method name}
+Violates:  "{rule text}" (CLAUDE.md §2)
+Fix:       {which layer/component should own this instead}
+```
+→ **Not auto-fixable.** Human must decide structural fix. Note required in Review Board.
+
+### T2 — Entity Consistency
+
+Using the loaded core-entities catalog:
+
+| Issue | Severity | Auto-fixable? |
+|-------|----------|---------------|
+| Entity mentioned not in core-entities.md | Major | No — human confirms if DTO or domain entity |
+| Field name differs from core-entities.md | Major | Yes — rename to canonical |
+| Relationship described differently | Major | No — human decides |
+| New entity introduced but not in core-entities.md | Minor | No — add to core-entities first |
+
+### T3 — BDD Traceability
+
+Cross-reference against the source `.feature` file:
+
+| Issue | Severity | Auto-fixable? |
+|-------|----------|---------------|
+| Tech-doc proposes behavior not in any BDD scenario | Major | No — create scenario first |
+| Tech-doc contradicts a BDD scenario | Critical | No — resolve conflict first |
+| UC scenario has no corresponding design decision | Minor | Yes — add missing design note |
+
+### T4 — Domain Conflict Check
+
+Compare against other tech-docs in `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/`:
+
+| Issue | Severity | Auto-fixable? |
+|-------|----------|---------------|
+| Same endpoint defined with different request/response | Critical | No — human resolves |
+| Same service method with different behavior | Critical | No — human resolves |
+| Entity status transitions differ between docs | Critical | No — human resolves |
+| Overlapping responsibility (both docs claim ownership of same logic) | Major | No — human resolves |
+
+### T5 — Internal Consistency
+
+Within the tech-doc itself:
+
+| Check | Severity | Auto-fixable? |
+|-------|----------|---------------|
+| Sequence diagram shows different flow than written description | Major | No |
+| API spec return type differs from code sketch | Major | Yes — align one to the other |
+| Section references a component/concept never defined later | Minor | Yes — add definition |
+| Assumption stated but no design addresses it | Minor | Yes — add note or remove assumption |
+
+### T6 — Structural Completeness
+
+Check all standard sections are present and non-empty:
+
+| Section | Missing severity |
+|---------|-----------------|
+| Header (`@trace.id`, `@trace.prd`, `@trace.domain`, `@trace.status`) | Major |
+| Overview / Context | Major |
+| Architecture Decision with rationale | Major |
+| Component Diagram or Layer Description | Major |
+| Sequence Diagram or Flow Steps | Major |
+| API Contract (if HTTP-facing) | Major |
+| Data Model Changes (if entity changes) | Major |
+| Error Handling Strategy | Major |
+| Open Questions / Assumptions | Minor |
+
+→ All T6 missing-section findings are **auto-fixable**: AI adds skeleton section with prompts.
+
+### T7 — Cross-Team API Contract Review
+
+*Only applies when ALL of the following are true:*
+*1. Source BDD has `@trace.platform: system`.*
+*2. Tech-doc header does NOT have `@trace.api_source: existing`.*
+
+*If `@trace.api_source: existing` → **skip T7 entirely**. Contract đã được PO xác định trong PRD — không có API design mới để đồng thuận.*
+
+This dimension ensures FE, App, and BE teams all agree on the API contract before implementation starts.
+
+**Step 1 — Check sign-off status in tech-doc header:**
+
+Read the `@trace.sign_off` block in the tech doc header. If absent → add it as a finding (auto-fixable: add skeleton).
+
+```yaml
+# @trace.sign_off:
+#   be_team:  pending    # author — set to "done" when BE satisfied with design
+#   fe_team:  pending    # FE/Web — must confirm contract matches web BDD expectations
+#   app_team: pending    # App — must confirm contract matches app BDD expectations (if applicable)
+#   sa:       pending    # SA/Tech Lead — final approval
+```
+
+**Step 2 — Contract vs BDD cross-check:**
+
+Load the web and app BDDs for this TICKET-ID (from `{paths.specs_dir}/{domain}/{prd-slug}/bdd/web/` and `{paths.specs_dir}/{domain}/{prd-slug}/bdd/app/` in the spec submodule or spec repo).
+
+For each platform BDD, verify the tech doc's API contract satisfies the BDD's `Then` clauses:
+
+| Check | Severity |
+|---|---|
+| Response fields in API contract don't cover what web BDD `Then` expects | Critical |
+| Response fields in API contract don't cover what app BDD `Then` expects | Critical |
+| Error response shape doesn't match what platform BDDs expect | Major |
+| System BDD `@system.resolution` annotation contradicts the API contract design | Critical |
+
+**Step 3 — Pending sign-off report:**
+
+After the review, list which sign-offs are still `pending`:
+
+```
+⏳ Pending sign-offs before tech docs can be approved:
+  fe_team  — FE/Web team must confirm API contract matches web BDD expectations
+  app_team — App team must confirm API contract matches app BDD expectations
+  sa       — SA/Tech Lead final approval
+
+Once sign-offs are collected → update @trace.sign_off in tech doc header, then re-run /review-tech-docs.
+Tech docs cannot be set to "approved" while any required sign-off is pending.
+```
+
+**Approval gate:**
+- If `be_team: done` AND `fe_team: done` AND `app_team: done` (or N/A) AND `sa: done` → tech docs may be set to `approved`
+- Otherwise → `@trace.status` stays `in-review` — `generate-code` is blocked
+
+---
+
+## Write Findings File
+
+After running all checks, write findings to `{paths.refinement_dir}/{uc-id}-tech-review-findings.yaml`:
+
+```yaml
+source_file: "{absolute path to tech-doc}"
+uc_id: "{UC-ID}"
+domain: "{domain}"
+generated_at: "{ISO datetime}"
+review_type: "tech-design"
+status: "pending_review"
+is_system_bdd: {true | false}  # true if source BDD has @trace.platform: system
+
+sign_off:                       # only present when is_system_bdd: true
+  be_team:  pending             # read from @trace.sign_off in tech-doc header
+  fe_team:  pending
+  app_team: pending             # "n/a" if project has no app platform
+  sa:       pending
+sign_off_gate: blocked          # blocked | ready — "ready" only when all required are "done"
+
+findings:
+  - id: "F001"
+    check_id: "T1"           # T1–T7
+    severity: "critical"     # critical | major | minor
+    section: "{section heading or component name where issue was found}"
+    uc_id: "{UC-ID}"         # same as top-level uc_id (the UC this tech-doc designs)
+    quote: "{verbatim snippet copied EXACTLY from the tech-doc at the issue location, ≤120 chars}"
+    finding: "{clear description of the violation or gap}"
+    suggestion: "{specific fix — AI applies this in --resume if accepted}"
+    auto_fixable: false      # true = AI can apply; false = human must write decision in note
+    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"
+  sign_off_gate: "{blocked — pending: fe_team, app_team, sa | ready}"
+```
+
+> **Locator fields (`quote` + `uc_id`) — required for Review Board source-jump.**
+> For every finding, copy a short **verbatim** `quote` straight from the tech-doc at the exact spot
+> the issue occurs — do NOT paraphrase; it is matched against the document to locate the line.
+> These let a reviewer click a finding in the Review Board and jump to the precise source location.
+
+## Report
+
+{{include:steps/report-footer.md}}
+
+```
+/review-tech-docs Complete — {target file}
+UC: {UC-ID} | Domain: {domain}
+Findings: {total} | 🔴 Critical: {N} | 🟡 Major: {N} | 🟢 Minor: {N}
+Auto-fixable: {N} | Needs human decision: {N}
+
+Sign-off gate (system BDD only):
+  be_team  : {done | pending}
+  fe_team  : {done | pending}   ← {name / "needs sign-off" }
+  app_team : {done | pending | n/a}
+  sa       : {done | pending}
+  Gate     : {🔒 BLOCKED — pending: fe_team, sa | ✅ READY}
+
+Findings file: {paths.refinement_dir}/{uc-id}-tech-review-findings.yaml
+Next: Open in Review Board → Accept/Modify/Reject each finding
+      Then run: /review-tech-docs --resume {tech-design-file}
+      After all sign-offs collected → update @trace.sign_off in tech doc, re-run review
+```
+
+---
+
+## Resume Mode — Apply Accepted Findings
+
+*Triggered when `$ARGUMENTS` contains `--resume`.*
+*Example: `/review-tech-docs --resume {paths.tech_docs_dir}/payment/{prd-slug}/tech-docs/PAY-UC1-tech-design.md`*
+
+### Phase 1 — Read accepted findings
+
+1. Derive findings file from target: `{paths.refinement_dir}/{uc-id}-tech-review-findings.yaml`
+2. Read the file. Collect findings where `status: "accepted"` or `status: "modified"`.
+3. If none → report "No accepted findings. File unchanged." and stop.
+
+### Phase 2 — Apply fixes
+
+Apply in order: critical → major → minor.
+
+| check_id | What to do |
+|----------|-----------|
+| T1 (Architecture) | Apply the structural fix from finding note — move logic to correct layer, update component description |
+| T2 (Field name) | Rename field to canonical name from core-entities.md throughout the document |
+| T3 (Missing design note) | Add design decision note for the uncovered scenario |
+| T5 (Internal inconsistency) | Align the conflicting sections to the decision stated in the note |
+| T6 (Missing section) | Add skeleton section with placeholder prompts for the tech lead to fill |
+
+**T1, T2, T4 findings with `auto_fixable: false`:** require a human-written resolution in the
+Review Board "Modify" note. Apply exactly what the note says. Do not invent the fix.
+
+### Phase 3 — Update header + TSV + Report
+
+Edit the tech-doc file directly:
+1. Find `@trace.revision:` in the header — increment its integer value by 1.
+2. Find `@trace.status:` in the header:
+   - If sign_off_gate = `ready` (all sign-offs done) → set to `approved`
+   - Otherwise → set to `in-review` (blocks `/generate-code`)
+3. If `@trace.sign_off` block is absent and this is a system BDD tech doc → add it with all values `pending`.
+
+Write both changes to the file.
+
+Then update `{paths.trace_dir}/{domain}/{prd-slug}/{UC-ID}.tsv` — pick the column by which tech-doc was reviewed (read the filename):
+- **BE contract** (`{UC-ID}-tech-design.md`) → set `tech_doc_revision` to the new `@trace.revision` integer for all rows of this UC.
+- **FE tech-design** (`{UC-ID}-tech-design-{platform}.md`) → set `fe_tech_doc_revision` instead, for the rows of this UC on that platform (leave `tech_doc_revision` untouched).
+- Set `last_updated` to today's date (`YYYY-MM-DD`) for all rows of this UC.
+
+Print the report after all file writes are complete.
+
+```
+/review-tech-docs --resume Applied — {target file}
+UC: {UC-ID}
+
+Applied  : {N} findings ({critical} critical, {major} major, {minor} minor)
+Skipped  : {N} rejected/deferred
+
+Changes:
+  - {change 1}
+  - {change 2}
+
+Revision : {old} → {new}
+Status   : {approved | in-review}
+
+Sign-off : {✅ All done — status set to approved
+           | 🔒 Pending: fe_team, sa — status set to in-review
+              Update @trace.sign_off in tech doc when each team confirms, then re-run /review-tech-docs}
+
+Re-run /review-tech-docs {file} to confirm 0 remaining critical findings.
+Next: {/generate-code {feature-file}  ← only if status = approved
+      | Collect pending sign-offs → update @trace.sign_off → re-run /review-tech-docs}
+      → if the tech-doc lives in the shared spec repo: commit + push it to the spec submodule so FE/App `/sync` the updated contract
+```