@edupia-tutor/spec-driven-docs 0.14.0

package/commands/review-context.md

@@ -0,0 +1,1047 @@
+# /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
+# Gate — Universal Entry Procedure
+
+Every command must execute this gate before proceeding with its specific logic.
+
+## Step 0 — Sub-Agent Mode Check
+
+Before anything else, check if `$ARGUMENTS` is a JSON payload from an orchestrator:
+
+1. Attempt to parse `$ARGUMENTS` as JSON.
+2. If it parses successfully **and** contains `"_agent_mode": true`:
+   - **Skip Steps 1, 2, and 3 of this Gate entirely.**
+   - Set target file = `payload.target_file`
+   - Set loaded context = `payload.context` (do NOT run context-loader.md)
+   - Set UC scope = `payload.uc_id` (process only this UC)
+   - Set line range = `payload.uc_section` (read only that PRD section)
+   - Proceed directly to the command-specific logic.
+3. If `$ARGUMENTS` is not JSON or `_agent_mode` is absent → continue to Step 1 (normal mode).
+
+## Step 0-B — Model Check
+
+*Skip this step if `_agent_mode: true` (sub-agent — orchestrator already validated).*
+
+Complex generation and review commands require strong reasoning.
+Using a smaller model risks missed edge cases, incomplete spec analysis, and architecture violations.
+
+Display and wait for response:
+
+```
+⚙️  MODEL CHECK
+──────────────────────────────────────────────────────────────────
+  Recommended  : claude-opus-4 (or latest Opus model)
+  Why needed   : Spec analysis, architecture review, code generation
+                 require deep reasoning. Smaller models miss edge cases.
+
+  To switch in Claude Code:
+    • Settings → Model → select "claude-opus"
+    • or: /model → choose claude-opus
+
+  Running on claude-opus?
+    Y — yes, on claude-opus → proceed
+    S — skip check (I accept lower quality risk with current model)
+──────────────────────────────────────────────────────────────────
+```
+
+- "Y" → proceed to Step 1.
+- "S" → proceed to Step 1 (user accepts risk, add ⚠️ to final report).
+- "N" or anything else → **STOP.** Output: "Please switch to claude-opus, then re-run this command."
+
+## Step 1 — Resolve Target File
+
+1. If `$ARGUMENTS` is provided and points to an existing file → use it directly as the target.
+2. If `$ARGUMENTS` is a **bare UC-ID / ticket ID / partial name** (no path) → resolve it to a file by globbing the feature-package layout. The `{prd-slug}` is **not known yet**, so use a `*` wildcard for that segment, and a recursive `**` under `bdd/` so the platform subfolders (`bdd/web/`, `bdd/app/`, `bdd/system/`) are all covered:
+   - **BDD commands** (target is a `.feature`): `{specs_dir}/{domain}/*/bdd/**/{UC-ID}*.feature` — or `{specs_dir}/*/*/bdd/**/{UC-ID}*.feature` if the domain is also unknown. If a platform/scope is implied by the command (e.g. a system tech-doc needs the `system/` BDD), prefer the match under that platform subfolder.
+   - **PRD commands** (target is `prd.md`): `{specs_dir}/{domain}/*/prd.md` (match the feature folder whose id corresponds), else `{specs_dir}/*/*/prd.md`.
+   - **tech-docs commands**: `{specs_dir}/{domain}/*/tech-docs/{UC-ID}*-tech-design*.md`.
+   - **design-spec commands**: `{specs_dir}/{domain}/*/design-spec/{TICKET-ID}*.md`.
+
+   Once a file matches: set it as the target **and** record `domain` + `prd_slug` from its path (per the extraction rule in `context-loader.md` Step 1 — `prd_slug` = first segment after `{specs_dir}/{domain}/`). Every path the command later reads or writes (sibling BDD/tech-docs/design-spec/trace) uses **that resolved `prd_slug`**, so all artifacts stay in one feature package. If several files match (e.g. multiple platforms), pick per the command's platform/scope or list them and ask.
+3. If `$ARGUMENTS` is empty or no match found:
+   - List files in the relevant directory for this command (e.g., `specs/*/*/prd.md` for PRD commands, `specs/*/*/bdd/**/*.feature` for BDD commands).
+   - Present the list to the user and ask: "Which file do you want to work with? (Enter number or filename)"
+   - Wait for user selection before continuing.
+
+## Step 2 — Execute Context Loader
+
+Load all project context by following the procedure in `steps/context-loader.md`.
+Store all loaded context in memory for use throughout this command session.
+
+## Step 3 — CHECKPOINT
+
+After completing Steps 1 and 2, display a summary and wait for confirmation:
+
+```
+CHECKPOINT
+-----------
+Target     : {resolved file path}
+Project    : {project.name from project-context.yaml}
+Tech stack : {language} / {framework}
+Module     : {module if set, else "not configured"}
+Domains    : {comma-separated domain list}
+
+Proceed? (Y/N)
+```
+
+Wait for explicit "Y" or "N" from the user before continuing.
+- "Y" → proceed to the command-specific steps below.
+- "N" → stop and ask what the user wants to change.
+
+
+*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
+# Context Loader — Load All Project Context
+
+Execute these steps in order. Store everything in memory for the duration of the command session.
+
+**Priority guide (anti-lost-in-middle):**
+- Steps 1–2 are PROJECT-CONFIG — loaded first, resolve all paths and metadata.
+- Step 3 is CRITICAL — architecture + coding standards, the highest-priority facts for generation.
+- Step 4 is SAFETY — data protection rules, enforced silently for the entire session.
+- Steps 5–6 are DOMAIN KNOWLEDGE — terminology and entity definitions.
+- Step 7 is the WORKING MEMORY RECAP — locks critical facts into the top of working memory.
+
+---
+
+## Step 1 — [PROJECT-CONFIG] Load project-context.yaml
+
+Read `.agent/project-context.yaml`. Extract and store:
+
+**Tech Stack:**
+- `tech_stack.language` → active language (e.g., Java 17, TypeScript, C#, Go)
+- `tech_stack.framework` → active framework (e.g., Spring Boot 3.2, Angular 17, .NET 8)
+- `tech_stack.build_tool` → build tool (e.g., Maven, npm, dotnet, go)
+- `tech_stack.test_framework` → test framework (e.g., JUnit 5 + Mockito, Jest, xUnit)
+- `tech_stack.database` → database (e.g., PostgreSQL, MySQL, MongoDB)
+- `tech_stack.module` → active module profile (e.g., java-spring, angular, dotnet, golang, context-engineering)
+
+**Conventions:**
+- `conventions.build_command` → how to compile/build
+- `conventions.test_command` → how to run tests
+- `conventions.service_run` → how to start the service
+- `conventions.ticket_prefix` → ticket ID prefix (e.g., PROJ, FEAT, UC)
+
+**Domains:**
+- `domains` → list of active business domains
+
+**Paths (if present):**
+- `paths.specs_dir` → spec artifacts root — PRD, BDD, tech-docs, design-spec. Structure: `{specs_dir}/{domain}/{prd-slug}/{prd.md | bdd/ | tech-docs/ | design-spec/}`
+- `paths.refinement_dir` → findings/review output dir
+- `paths.qc_dir` → QC automation artifacts root (visible top-level, one subfolder per UC: `{qc_dir}/{UC-ID}/`)
+- `paths.qc_skills_dir` → where qc-* commands load QC skills from (default bundled `.agent/skills/qc`; override to the QC team's own repo/submodule so framework upgrade won't overwrite them)
+- `paths.product_definitions_dir` → product definitions root
+- `paths.domain_knowledge_dir` → domain knowledge root
+- `paths.business_dictionary` → path to business-dictionary.md
+- `paths.core_entities` → path to core-entities.md
+- `paths.tech_docs_dir` → technical documentation root (merged with specs_dir in feature-package layout — tech-docs live under `{specs_dir}/{domain}/{prd-slug}/tech-docs/`)
+- `paths.trace_dir` → trace state directory; structure: `.trace/{domain}/{prd-slug}/{UC-ID}.tsv`
+
+If `paths` section is absent, use these defaults:
+- `specs_dir` = `specs`
+- `refinement_dir` = `.agent/review`
+- `qc_dir` = `docs`
+- `qc_skills_dir` = `.agent/skills/qc`
+- `product_definitions_dir` = `specs/product-definition`
+- `domain_knowledge_dir` = `specs/domain-knowledge`
+- `business_dictionary` = `specs/domain-knowledge/business-dictionary.md`
+- `core_entities` = `specs/domain-knowledge/core-entities.md`
+- `tech_docs_dir` = `specs`
+- `trace_dir` = `.trace`
+
+Note: In the feature-package layout, `specs_dir` is the unified root. All spec artifact types (PRD, BDD, tech-docs, design-spec) live under `{specs_dir}/{domain}/{prd-slug}/`. The `prd-slug` is the feature-package folder name, not a separate config variable.
+
+**How to extract `prd_slug` (works for ANY target file, regardless of nesting depth):** given a target path of the form `{specs_dir}/{domain}/{prd-slug}/...`, take the **first path segment after `{specs_dir}/{domain}/`** — i.e. the `{prd-slug}` position. Do NOT use the file's immediate parent folder, because BDD/tech-docs/design-spec artifacts are nested one or two levels deeper inside the package. Examples:
+- `specs/payment/create-invoice/prd.md` → `prd_slug = create-invoice`
+- `specs/payment/create-invoice/bdd/system/PAY-UC1.feature` → `prd_slug = create-invoice` *(NOT `system`)*
+- `specs/payment/create-invoice/bdd/web/PAY-UC1.feature` → `prd_slug = create-invoice` *(NOT `web`)*
+- `specs/payment/create-invoice/tech-docs/PAY-UC1-tech-design.md` → `prd_slug = create-invoice` *(NOT `tech-docs`)*
+- `specs/payment/create-invoice/design-spec/PAY-design-spec-web.md` → `prd_slug = create-invoice`
+
+All sibling artifacts of one feature (PRD, every platform's BDD, the BE + FE tech-docs, the design-spec, and the trace TSV) therefore resolve to the **same `prd_slug`** — so a synthesized **system** BDD or **system/BE** tech-doc lands in the same `{specs_dir}/{domain}/{prd-slug}/` package as the web/app artifacts it was derived from.
+
+If `tech_stack.module` is set, also load `.agent/modules/{module}/stack-profile.yaml` if it exists.
+
+---
+
+## Step 1.5 — [SERVICE ROUTING] Resolve service paths (umbrella mode)
+
+*Skip this step entirely if `setup.mode` is not `"umbrella"` and `services` section is absent from project-context.yaml.*
+
+If `services` section is present:
+
+**1. Detect active domain** (in priority order):
+- Read `@trace.domain` from target file frontmatter (if Gate loaded a target file)
+- Extract from target file path: `domain` = the first segment after the `specs_dir` base path; `prd_slug` = the next segment (the feature-package folder). This holds for any target depth — see the `prd_slug` extraction rule in Step 1.  
+  *(e.g., `specs/user/create-account/prd.md` **and** `specs/user/create-account/bdd/system/UC1.feature` both → domain = `user`, prd_slug = `create-account`)*
+- If `$ARGUMENTS` contains a path, extract the domain segment after `specs_dir`
+
+**2. Route to service** — if active domain matches a key in `services`:
+- Override `paths.specs_dir` → `services.{domain}.specs_dir` — **only if `setup.spec_source` is NOT set.** When `spec_source` IS set, ALL BDD (web/app/**system**) is a shared cross-team artifact → leave `specs_dir` for step 4 to route to the spec repo; do NOT pin it per-service here.
+- Override `paths.tech_docs_dir` → `services.{domain}.tech_docs_dir` — **only if `setup.spec_source` is NOT set.** When `spec_source` IS set, the tech-design (API contract) is a cross-team artifact and must live in the shared spec repo (handled in step 4), so leave `tech_docs_dir` for step 4 to route — do NOT pin it per-service here.
+- Store `active_service` = `services.{domain}.path`
+- Store `active_service_module` = `services.{domain}.module`
+- If service has its own `module` → use it as `active_module` (overrides `tech_stack.module`)
+
+**3. Fallback** — if domain not detected or no matching service key:
+- Keep default paths from Step 1
+- Set `active_service = unresolved`
+
+**4. Spec source auto-override** — if `setup.spec_source` is set AND the corresponding path was not already explicitly set in `paths:`:
+- Override `paths.specs_dir` → `{spec_source}/specs` — **always when `spec_source` is set.** All spec artifacts (PRD, BDD, tech-docs, design-spec) live under the unified spec root in the shared spec repo using the feature-package layout: `{spec_source}/specs/{domain}/{prd-slug}/`. Every umbrella (FE/App/BE) reads from here. *(Per-service `specs/` only when there is no `spec_source`.)*
+- Override `paths.tech_docs_dir` → `{spec_source}/specs` — **always when `spec_source` is set** (step 2 no longer pins tech-docs per-service in this case). Tech-docs live at `{spec_source}/specs/{domain}/{prd-slug}/tech-docs/`. The tech-design IS the cross-team API contract: BE authors it here, and FE/App read it from the same spec submodule at `/generate-code --phase=integration`. *(Per-service tech-docs only happen when there is no `spec_source` — a pure multi-service BE repo with no shared spec module.)*
+- Override `paths.domain_knowledge_dir` → `{spec_source}/specs/domain-knowledge`
+- Override `paths.business_dictionary` → `{spec_source}/specs/domain-knowledge/business-dictionary.md`
+- Override `paths.core_entities` → `{spec_source}/specs/domain-knowledge/core-entities.md`
+- Override `paths.bug_reports_dir` → `{spec_source}/feedback/bug-reports`
+- Override `paths.bdd_proposals_dir` → `{spec_source}/feedback/bdd-proposals`
+- Override `paths.prd_change_requests_dir` → `{spec_source}/feedback/prd-change-requests`
+- Override `paths.trace_dir` → `{spec_source}/.trace` — **always when `spec_source` is set.** Trace TSVs are consolidated in the spec repo (single authoritative location, no per-service split) so the PM/PO has one place to manage status. Internal structure: `.trace/{domain}/{prd-slug}/{UC-ID}.tsv`. Code-side commands (`/generate-code`, `/dev-run-test`, `/qc-run-test`) run from `service_root` but **write their trace row into `{spec_source}/.trace/{domain}/{prd-slug}/`** — like they already push `feedback/` there. *(Per-service `.trace` only when there is no `spec_source`.)*
+
+> **Why under `spec_source`:** PRD, BDD, tech-docs, design-spec, domain knowledge, tester feedback, **and the `.trace/` coverage state** are all **cross-team artifacts** — they live in the **shared spec repo** using the feature-package layout so every umbrella (FE/App/BE) and the PM read one source via `/sync`. In the feature-package layout, a single `specs/{domain}/{prd-slug}/` folder groups all artifact types for one PRD, making the spec repo self-contained and navigable by feature. The service submodule holds only **code** (+ build/test tooling). `.trace/` and `feedback/` are the dev/QC **write areas** in the spec repo. In single-service mode (no `spec_source`), everything defaults under the repo root — still one repo.
+
+---
+
+## Step 1.6 — [SERVICE CONVENTIONS] Load service-specific conventions (umbrella mode)
+
+*Skip this step entirely if `active_service` is `"unresolved"` or context is single-service mode.*
+
+When `active_service` has been resolved to a real path in Step 1.5 (e.g., `user-service/`):
+
+**1. Locate service config** — try in priority order:
+- `{active_service}/.agent/project-context.yaml`
+- `{active_service}/project-context.yaml`
+
+**2. If found, override with service-specific values:**
+
+| Variable | Source |
+|----------|--------|
+| `conventions.test_command` | service's `conventions.test_command` |
+| `conventions.build_command` | service's `conventions.build_command` |
+| `paths.trace_dir` | **If `spec_source` is set → keep the Step 4 spec-repo route (`{spec_source}/.trace`); ignore any service-level `trace_dir`.** Only when there is no `spec_source`: `{active_service}/{service paths.trace_dir}` (default `{active_service}/.trace`). |
+| `paths.specs_dir` | **If `spec_source` is set → keep the Step 4 spec-repo route (`{spec_source}/specs`); ignore any service-level `specs_dir`** (all spec artifacts are cross-team, never per-service in this mode). Only when there is no `spec_source`: `{active_service}/{service paths.specs_dir}` if set, else the Step 1.5 override. |
+
+**3. Store** `service_root = {active_service}` as the working directory anchor for all downstream commands:
+- Shell commands (`/dev-run-test`, `/dev-gen-test`) run **from within** `service_root`
+- **Source/test files** are written relative to `service_root`; **trace TSVs** are written to `{paths.trace_dir}` (the spec repo when `spec_source` is set — a cross-repo write, committed/pushed to the spec submodule like `feedback/`).
+
+**4. If service config not found** — keep umbrella defaults, still set `service_root = {active_service}` (path anchor is always needed even without a config override).
+
+---
+
+## Step 2 — [PROJECT-CONFIG] Load module stack profile (conditional)
+
+If `tech_stack.module` is set, read `.agent/modules/{module}/stack-profile.yaml`.
+Merge framework-specific conventions (layer patterns, test patterns, naming rules) into the loaded context.
+If the file does not exist → skip silently.
+
+---
+
+## Step 3 — [CRITICAL] Load CLAUDE.md (layered: root + service overlay)
+
+*This is the highest-priority context — it defines HOW to write code and documents for this project.*
+
+CLAUDE.md is loaded in **two layers** so umbrella-wide rules and service-specific
+architecture/coding standards compose correctly. The agent always sits at the umbrella
+root, but the implementation code lives in a service submodule with its OWN stack,
+architecture, and conventions — so the service's CLAUDE.md must win for code generation.
+
+**Layer 1 — [BASE] Root CLAUDE.md (umbrella-wide).**
+Read `CLAUDE.md` at the repo root. Treat its contents as the **shared baseline** for the
+whole umbrella — git conventions, data-protection posture, cross-cutting rules, and (in
+single-service mode) the project's only architecture + coding standards.
+
+**Layer 2 — [OVERLAY] Service CLAUDE.md (umbrella mode only).**
+*Run only if `service_root` was set in Step 1.6 (i.e. a real service was routed to).*
+Read `{service_root}/CLAUDE.md`. This file defines the architecture + coding standards of
+the **actual stack being implemented** (e.g. `user-service` = java-spring, `web` = nextjs).
+Overlay it on top of Layer 1: **on any conflict, the service value WINS** for architecture,
+coding standards, and error handling. Layer-1 values that the service does not redefine
+(e.g. git conventions, banned patterns shared org-wide) remain in effect.
+
+From the **merged** result, extract and store:
+
+- **§1 Project Overview** → project name, language, framework, build/test commands, domains
+- **§2 Architecture** → layer order (e.g., Controller → Facade → Service → Repository), architectural rules — *service overlay wins*
+- **§3 Coding Standards** → naming conventions (classes, methods), response wrapper type, forbidden patterns — *service overlay wins*
+- **§5 Error Handling** → exception types, HTTP status code mapping, not-found exception class name — *service overlay wins*
+- **§7 Git Conventions** → branch naming pattern, commit message format — *root baseline unless service redefines*
+
+**Resolution rules:**
+- If both layers exist → merge as above; record `claude_md_source = root + {service_root}`.
+- If only the service overlay exists (no root CLAUDE.md) → use the service file alone; `claude_md_source = {service_root}`.
+- If `service_root` is set but `{service_root}/CLAUDE.md` is **missing** → fall back to root CLAUDE.md and flag ⚠️ in the Step 7 recap (the service has no architecture/coding-standards definition — code generation will use umbrella defaults, which may be the wrong stack).
+- If neither exists → note CLAUDE.md as missing and continue with project-context.yaml data only.
+
+---
+
+## Step 4 — [SAFETY] Load Data Protection Rules
+
+Read `.agent/rules/data-protection.md` (or `rules/data-protection.md` from the framework installation).
+
+Store the sensitive file patterns — you must **never** read, write, display, or reference content from files matching those patterns for the entire session.
+
+If neither file exists → apply built-in defaults: never access `.env*`, `*.key`, `*.pem`, `*secret*`, `*password*`, `*credential*`.
+
+---
+
+## Step 5 — [DOMAIN] Load Business Dictionary (conditional)
+
+Check if the business dictionary file exists (use `paths.business_dictionary` resolved in Step 1).
+
+If it exists, read it and extract:
+- **Canonical Terms** → complete list of approved terms and their definitions
+- **Banned Terms** → complete list of banned terms and their canonical replacements
+- **Status / Enum Registry** → allowed enum values per entity
+
+Store the banned terms list for **active enforcement** throughout the command session:
+- When generating any text (PRD, BDD, code comments, tech docs), verify no banned terms appear
+- Replace banned terms with their canonical equivalents automatically
+
+If the file does not exist → skip silently. Do not warn or block.
+
+---
+
+## Step 6 — [DOMAIN] Load Core Entities (conditional)
+
+Check if the core entities file exists at `paths.core_entities` (resolved in Step 1).
+Default path: `specs/domain-knowledge/core-entities.md`.
+
+If it exists, read it and store:
+- **Entity catalog** → for each entity: its name, purpose, owner service, key fields (name + type), business invariants, and relationships
+- **Field name registry** → canonical field names to use in generated code and documents
+- **Relationship map** → how entities relate to each other (1:N, N:N, embedded, etc.)
+
+**How to use this catalog:**
+- When generating code: use the field names, types, and relationships defined here — do NOT infer from existing code
+- When generating PRD/BDD: reference entity names from this catalog for consistency
+- When generating tech-docs: use this catalog as the source-of-truth for entity definitions
+
+If the file does not exist → skip silently.
+
+---
+
+## Step 6.5 — [PLATFORM] Derive active_module and platform_type
+
+Using `tech_stack.module` loaded in Step 1, derive and store two variables for use by all downstream commands:
+
+```
+active_module = tech_stack.module   (e.g. "java-spring", "react", "flutter")
+```
+
+| `platform_type` | Modules |
+|---|---|
+| `backend` | `java-spring`, `golang`, `dotnet`, `php-laravel`, `context-engineering` |
+| `web-frontend` | `react`, `nextjs`, `vue`, `nuxt`, `angular` |
+| `mobile` | `flutter`, `react-native`, `ios-swiftui`, `android-compose` |
+
+If `tech_stack.module` is blank or not recognized → set `platform_type = "unknown"` and flag as ⚠️ in the Step 7 recap.
+
+These two variables (`active_module`, `platform_type`) are the canonical source for all branching logic in commands that need platform-specific behavior (dev-gen-test, debug, fix-bug, dev-smoke-test).
+
+---
+
+## Step 6.7 — [GUARDRAILS] Load Project Lessons (conditional)
+
+*Accumulated mistakes the AI must not repeat in this project. These are added over time via `/learn`
+or accepted during `/review-code`, `/fix-bug`, `/debug`.*
+
+Resolve the lessons file path:
+- Use `paths.lessons_file` if set (may be service-overridden in umbrella mode, Step 1.6)
+- Else default `specs/domain-knowledge/lessons-learned.md`
+- In umbrella/service mode (when `service_root` is set), if `paths.lessons_file` is unset, default to `{service_root}/.agent/project-lessons.md`
+
+If the file exists, read it and store ALL lessons as **ACTIVE GUARDRAILS** for the session:
+- Treat each lesson's **Rule** as a hard constraint — same priority as CLAUDE.md coding standards (Step 3).
+- Before generating or modifying any artifact (PRD, BDD, tech-doc, code, test), check the output against every lesson whose `category` matches the current command AND whose `scope` matches the target (domain / file).
+- If a generated output would violate a lesson → correct it **before** presenting, and note which lesson (`L-NNN`) was applied.
+
+If the file does not exist → skip silently (no lessons captured yet).
+
+---
+
+## Step 7 — [RECAP] Working Memory Recap (anti-lost-in-middle)
+
+After loading all context, synthesize and output a compact summary block.
+This recap ensures the most critical facts are stated at the END of context loading
+(recency effect — freshest in working memory when the task begins).
+
+Output exactly this block:
+```
+[CTX LOADED]
+Stack     : {language} / {framework} / {database}
+Platform  : {active_module} ({platform_type})
+Layers    : {layer order from merged CLAUDE.md §2, e.g., Controller → Facade → Service → Repository}
+CLAUDE.md : {root + {service_root} | {service_root} only | root only | ⚠️ service overlay MISSING — using root | missing}
+Ticket    : {ticket_prefix}-
+Dict      : {loaded — N canonical terms, M banned terms | missing}
+Entities  : {loaded — EntityA, EntityB, EntityC | missing}
+Lessons   : {loaded — N guardrails | none yet}
+Service   : {active_service} ({active_service_module}) | single-service
+Svc Root  : {service_root} — conventions + trace_dir loaded from service config | —
+Status    : {FULL | PARTIAL — missing: CLAUDE.md / business-dict / core-entities | MINIMAL}
+```
+
+If any CRITICAL file is missing (CLAUDE.md), flag it clearly so the user can decide whether to proceed.
+
+---
+
+## Context Load Complete
+
+After completing all steps, you have loaded:
+- Project identity, tech stack, module conventions
+- Architecture rules and layer order  ← **[CRITICAL — hold in working memory]**
+- Coding standards and naming conventions  ← **[CRITICAL — hold in working memory]**
+- Data protection rules (sensitive file patterns to never access)
+- Terminology rules with banned-term list  ← **[DOMAIN — apply to every generated word]**
+- Entity catalog (field names, types, invariants)  ← **[DOMAIN — use for code generation]**
+- All configured paths
+
+Proceed to the next step of the calling command.
+
+
+---
+
+## 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
+# Exhaustive Review Fan-Out + Completeness Convergence
+
+**Why this exists:** A single-pass review never lists every issue at once — the model
+stops at "enough" findings, so each later review round surfaces *new* problems
+(whack-a-mole). This procedure forces the review to **converge in one command run**:
+fan out across review dimensions in parallel, then loop a completeness critic until a
+round produces nothing new, *before* writing the findings file.
+
+The calling command supplies two things:
+- **DIMENSIONS** — the list of review dimensions to fan out over
+  (`/refine-prd` → the 4 lenses; `/review-context` → the P-checks or B-checks).
+- **FINDINGS SCHEMA** — the YAML shape each finding must follow (defined in the command).
+
+> **Sub-agent mode bypass:** If Gate Step 0 set `_agent_mode: true`, this whole
+> procedure is **skipped** — the orchestrator is already running one dimension/UC per
+> sub-agent. Run the command's checks directly on the scoped section and return findings.
+
+---
+
+## Phase 1 — Parallel dimension scan
+
+**How many sub-agents:** the agent *count* is not the completeness lever — breadth is
+fixed by the DIMENSION taxonomy (adding agents to the same dimension just re-finds the
+same issues), and *depth* is owned by the Phase 2 critic loop. Pick the **fan-out
+granularity** by target size, reusing the `steps/spawn-agent.md` thresholds:
+
+| Target size | Granularity | Agent count |
+|-------------|-------------|-------------|
+| ≤ 3 UCs **and** ≤ 300 lines | one agent per DIMENSION over the whole file | = number of dimensions |
+| > 3 UCs **or** > 300 lines | one agent per **DIMENSION × UC-scope** (UCs + a PRD-global scope), batched to fit the agent cap | `dimensions × (UCs + 1)`, capped (see below) |
+
+The larger granularity keeps each sub-agent's context small and its scan exhaustive on a
+single UC — which is what prevents misses on big PRDs.
+
+> **Global (non-UC) sections — required in `DIMENSION × UC` mode.** Per-UC agents only
+> see one UC each, so PRD-wide sections that belong to no UC (scope, success metrics,
+> problem statement, terminology, glossary, changelog) would go unscanned. Whenever you
+> fan out per UC, also include a **"PRD-global"** scope (the non-UC sections, findings get
+> `uc_id: ""`) alongside the UC list. So the natural agent count is `dimensions × (UCs + 1)`.
+> (Not needed in the whole-file mode — there each agent already sees the global sections.)
+
+### Agent cap — batch UCs when the fan-out gets too wide
+
+`dimensions × (UCs + 1)` can explode on large PRDs (e.g. 6 checks × (8 UCs + 1) = 54
+agents). Cap the wave at **`AGENT_CAP = 12`** agents and batch UC scopes to fit:
+
+1. Build the scope list = `[UC1, UC2, …, UCn, PRD-global]` (length `UCs + 1`).
+2. Compute scopes-per-agent-bucket: `groups = max(1, floor(AGENT_CAP / dimensions))`.
+   - If `groups ≥ UCs + 1` → no batching needed, run one agent per `DIMENSION × scope`.
+   - Else split the scope list into `groups` contiguous buckets of roughly equal size
+     (keep `PRD-global` in its own bucket if it fits; otherwise append it to the last
+     bucket). Each agent then handles **one DIMENSION over one bucket of UCs**.
+3. Resulting wave size = `dimensions × groups ≤ AGENT_CAP`.
+
+A batched agent reviews several UCs at once — still scoped far tighter than the whole
+file, so coverage stays high. `AGENT_CAP` is the only knob; raise it if the host allows
+more concurrency, lower it to save tokens. Whole-file mode (≤ 3 UCs) never hits the cap.
+
+Spawn the chosen sub-agents using the Agent tool (send them in a single message so they
+run concurrently). Each sub-agent gets a **fresh context window** and scans its scope
+through its **one** dimension only — deeper coverage than one session juggling every
+dimension at once (avoids lost-in-the-middle).
+
+Sub-agent prompt template (fill the braces):
+
+```
+You are a {DIMENSION_NAME} reviewer. Read the full target file at {target_file}.
+Scope: review ONLY through the {DIMENSION_NAME} lens/check — {DIMENSION_DESCRIPTION}.
+Be exhaustive: scan every section, every UC, every AC/BR/scenario. Do not stop early.
+Project context (terminology, entities, architecture):
+{slim_context — banned terms, canonical entities, layer order, domains}
+
+Return a JSON array of findings, each:
+{ "dimension": "{DIMENSION_NAME}", "severity": "critical|major|minor",
+  "section": "...", "uc_id": "...", "quote": "<verbatim ≤120 chars>",
+  "finding": "...", "suggestion": "...", "auto_fixable": true|false }
+Return [] if this dimension is clean. Return ONLY the JSON array.
+```
+
+Collect every sub-agent's array into one consolidated list `ALL_FINDINGS`.
+
+---
+
+## Phase 2 — Completeness-critic convergence loop
+
+This is the anti-whack-a-mole step. Repeat until **two consecutive rounds add zero new
+findings**, or a hard cap of **3 rounds**, whichever comes first:
+
+1. Spawn one **completeness-critic** sub-agent with the Agent tool. Give it:
+   - the full target file (`{target_file}`),
+   - the current `ALL_FINDINGS` list (so it knows what is already captured),
+   - the same slim context.
+   Prompt it:
+   ```
+   Here is a document and a list of issues already found. Read the WHOLE document.
+   List ONLY real, additional issues NOT already in the list — gaps, ambiguities,
+   contradictions, missing edge/negative paths, coverage holes, terminology drift,
+   structural omissions, and any issue that a fix to an existing finding would expose.
+   Do NOT repeat anything already listed. Return the same finding JSON shape, or [] if
+   nothing new.
+   ```
+2. Append any genuinely new findings (not already in `ALL_FINDINGS`) to the list.
+3. If this round returned 0 new → increment the dry-round counter; else reset it to 0.
+4. Stop when dry-round counter reaches 2, or after 3 rounds total.
+
+Record `convergence_rounds` (how many critic rounds ran) for the report.
+
+---
+
+## Phase 3 — Dedup, resolve conflicts, merge
+
+Sub-agents run **blind to each other** (independence = diverse coverage). They never
+talk or reconcile among themselves — all duplicate/conflict resolution happens **here in
+the orchestrator**, where the full set is visible.
+
+1. **Deduplicate** `ALL_FINDINGS`: two findings are duplicates if they target the same
+   `section` + `uc_id` and describe the same underlying issue. Keep the one with the
+   richer `suggestion`; if they differ on severity, keep the **higher** severity.
+2. **Resolve conflicts** — group remaining findings by `section` + `uc_id` and check for
+   contradictions (two findings whose `suggestion`s cannot both be applied, or that
+   propose opposite fixes for the same spot):
+   - If the two suggestions can be **merged** into one coherent fix → merge them into a
+     single finding.
+   - If they are **mutually exclusive** → emit **one** finding that states both options
+     and set `auto_fixable: false` with `status: "needs_discussion"` (PRD) /
+     `status: "pending"` (review) so a human picks — never silently drop one side.
+   - If a finding is **invalidated** by another (e.g. a structural finding says a section
+     is missing, but another quotes content from it) → drop the invalid one.
+3. **Sort** by severity (critical → major → minor), then by `section` order in the file.
+4. **Assign stable IDs** `F001, F002, …` in that sorted order.
+5. Map each finding's `dimension` into the command's schema field
+   (`lens` for `/refine-prd`; `check_id` for `/review-context`).
+6. Write the **single** findings file in the FINDINGS SCHEMA the command defines.
+
+In the command's final report, add one line:
+```
+Convergence: {convergence_rounds} critic round(s) — findings file is complete; re-running should surface 0 new issues.
+```
+
+
+**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
+
+# Report Footer — Standard Command Output Format
+
+Every command report must end with this standard footer section.
+
+## Status Badge
+
+Choose one based on outcome:
+- `✅ Complete` — all steps succeeded, no issues found
+- `❌ Failed` — command could not complete due to a blocking error
+- `⚠️ Warnings` — completed with non-blocking issues that should be reviewed
+
+## Output Artifacts
+
+List every file created or modified by this command:
+```
+Output Artifacts:
+  {created|updated} {file-path} ({brief description})
+  {created|updated} {file-path} ({brief description})
+```
+
+If no files were written (e.g., review or analysis commands) → write `Output Artifacts: none (read-only)`.
+
+## Pipeline Position
+
+Print a one-line map of the pipeline with the CURRENT command's phase marked `◀ bạn ở đây`,
+so the user always sees where this command sits in the end-to-end flow:
+
+```
+Discovery → PRD → [Design Spec] → BDD → Tech Design → Code → Dev Self-Check → QC → Trace Audit
+```
+
+Find the current command in this phase legend and mark **its** phase in the map above:
+
+| Phase | Commands |
+|-------|----------|
+| Discovery | `/define-product` |
+| PRD | `/generate-prd` · `/refine-prd` · `/review-context` (PRD) |
+| Design Spec | `/generate-design-spec` |
+| BDD | `/generate-bdd` · `/review-context` (BDD) |
+| Tech Design | `/generate-tech-docs` · `/map-testids` · `/review-tech-docs` |
+| Code | `/generate-code` · `/review-code` |
+| Dev Self-Check | `/dev-gen-test` · `/dev-run-test` · `/dev-smoke-test` |
+| QC | `/qc-analyze` · `/qc-plan` · `/qc-design-test` · `/qc-review` · `/qc-run-test` · `/qc-report` |
+| Trace Audit | `/validate-traces` |
+
+For a **review command**, also append the 3-step review loop with the current step marked, e.g.:
+`Vòng review: [① phân tích ◀] → ② Review Board → ③ --resume`.
+
+**Cross-cutting commands** (`/sync`, `/update-framework`, `/fix-bug`, `/debug`, `/learn`,
+`/report-bug`, `/propose-scenario`, `/generate-spec-manifest`) sit outside the linear pipeline —
+**omit the Pipeline line entirely** for these (do not force-fit them onto the map).
+
+## Next Command Suggestion
+
+Suggest the logical next command based on workflow phase:
+
+| Current command         | Suggest next                                  |
+|-------------------------|-----------------------------------------------|
+| /setup-ai-first         | `/define-product` to start your first feature |
+| /define-product         | `/generate-prd {product-definition-file}`     |
+| /generate-prd           | `/refine-prd {prd-file}` then `/review-context {prd-file}` |
+| /refine-prd             | Open Review Board → update PRD → `/review-context {prd-file}` |
+| /review-context (PRD)   | FE/App: `/generate-design-spec {prd-file}` (then BDD after sign-off); BE: `/generate-bdd {prd-file}` directly; fix PRD if NEEDS_FIX |
+| /generate-design-spec   | Designer review → Figma links confirmed → PO + Designer sign-off → `/generate-bdd {prd-file}` |
+| /generate-bdd           | `/review-context {feature-file}` to verify coverage |
+| /review-context (BDD)   | `/generate-tech-docs {UC-ID}` if APPROVED; regenerate if NEEDS_FIX |
+| /qc-analyze             | `/qc-plan {UC-ID}` (resolve 🔴 blocker gaps first) |
+| /qc-plan                | `/qc-design-test {UC-ID}`                     |
+| /qc-design-test         | `/qc-review {UC-ID}` (test-case review)       |
+| /qc-review (test-case)  | `/qc-run-test {UC-ID}` if APPROVED; fix TCs if NEEDS_FIX |
+| /qc-run-test            | `/qc-report {UC-ID}` then `/qc-review {UC-ID}` (script review) |
+| /qc-review (script)     | `/qc-report {UC-ID}` then create PR if APPROVED |
+| /qc-report              | `/validate-traces {UC-ID}` to refresh Living Docs (qc_status) |
+| /generate-tech-docs     | `/review-tech-docs {tech-design-file}`        |
+| /review-tech-docs       | `/generate-code {feature-file}` if APPROVED; fix doc if NEEDS_FIX |
+| /generate-code          | First gen → `/review-code {UC-ID}`; re-gen → `/dev-gen-test {UC-ID}` |
+| /dev-gen-test         | `/dev-run-test {UC-ID}`                          |
+| /dev-run-test (passing)    | `/review-code {UC-ID}`                        |
+| /dev-run-test (failing)    | `/fix-bug {ticket-id}` or `/debug {error}`    |
+| /review-code            | `/dev-smoke-test {UC-ID}` or create PR            |
+| /dev-smoke-test             | Create PR and link to ticket                  |
+| /validate-traces        | DRIFT/UNTRACKED → `/generate-code {UC-ID}`; GAP → `/dev-gen-test {UC-ID}`; all OK → create PR |
+| /fix-bug                | Create PR and link to ticket                  |
+| /debug                  | `/fix-bug {ticket-id}` if fix needed          |
+| /report-bug             | Send to dev (`/fix-bug {BUG-ID}`); if coverage gap → `/propose-scenario {UC-ID}` |
+| /propose-scenario       | Notify PO/Dev to review the proposal in `feedback/bdd-proposals/` |
+| /learn                  | Continue working — lesson applies on next command |
+| /sync                   | `/validate-traces` for full coverage; act on any `📥 tester feedback` surfaced |
+| /update-framework       | Review `git diff .agent/`, commit; `/sync` for project content |
+
+Format the footer as:
+```
+---
+Status   : {badge}
+{Output Artifacts block}
+Pipeline : Discovery → PRD → [BDD ◀ bạn ở đây] → Tech Design → Code → Dev Self-Check → QC → Trace Audit
+           (review cmd) Vòng review: [① phân tích ◀] → ② Review Board → ③ --resume
+Next     : {suggested command with example arguments}
+```
+*(Omit the `Pipeline` line for cross-cutting commands listed above.)*
+
+
+```
+/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.
+```