@anhth2/spec-driven-dev-plugin 0.6.0 → 0.8.0

package/commands/review-tech-docs.md

@@ -34,7 +34,7 @@ Display and wait for response:
 ```
 ⚙️  MODEL CHECK
 ──────────────────────────────────────────────────────────────────
-  Recommended  : claude-opus-4-5 (or claude-opus-4)
+  Recommended  : claude-opus-4 (or latest Opus model)
   Why needed   : Spec analysis, architecture review, code generation
                  require deep reasoning. Smaller models miss edge cases.
 
@@ -135,6 +135,7 @@ Read `.agent/project-context.yaml`. Extract and store:
 - `paths.core_entities` → path to core-entities.md
 - `paths.tech_docs_dir` → technical documentation root
 - `paths.trace_dir` → trace state directory
+- `paths.design_spec_dir` → Design Spec documents root (FE/App only)
 
 If `paths` section is absent, use these defaults:
 - `specs_dir` = `specs/bdd`
@@ -144,13 +145,46 @@ If `paths` section is absent, use these defaults:
 - `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` = `tech-docs`
+- `tech_docs_dir` = `specs/tech-docs`
 - `trace_dir` = `.trace`
+- `design_spec_dir` = `specs/design-spec`
 
 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: segment immediately after `prd_dir` base path  
+  *(e.g., `specs/prd/user/FEAT-01.md` → domain = `user`)*
+- If `$ARGUMENTS` contains a path, extract the segment after `prd_dir`
+
+**2. Route to service** — if active domain matches a key in `services`:
+- Override `paths.specs_dir` → `services.{domain}.specs_dir`
+- Override `paths.tech_docs_dir` → `services.{domain}.tech_docs_dir`
+- 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.prd_dir` → `{spec_source}/specs/prd`
+- Override `paths.design_spec_dir` → `{spec_source}/specs/design-spec`
+- 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`
+
+---
+
 ## Step 2 — [PROJECT-CONFIG] Load module stack profile (conditional)
 
 If `tech_stack.module` is set, read `.agent/modules/{module}/stack-profile.yaml`.
@@ -221,6 +255,26 @@ 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 (generate-tests, debug, fix-bug, smoke-test).
+
+---
+
 ## Step 7 — [RECAP] Working Memory Recap (anti-lost-in-middle)
 
 After loading all context, synthesize and output a compact summary block.
@@ -231,10 +285,12 @@ Output exactly this block:
 ```
 [CTX LOADED]
 Stack     : {language} / {framework} / {database}
+Platform  : {active_module} ({platform_type})
 Layers    : {layer order from CLAUDE.md §2, e.g., Controller → Facade → Service → Repository}
 Ticket    : {ticket_prefix}-
 Dict      : {loaded — N canonical terms, M banned terms | missing}
 Entities  : {loaded — EntityA, EntityB, EntityC | missing}
+Service   : {active_service} ({active_service_module}) | single-service
 Status    : {FULL | PARTIAL — missing: CLAUDE.md / business-dict / core-entities | MINIMAL}
 ```
 
@@ -428,21 +484,23 @@ 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)   | `/generate-bdd {prd-file}` if APPROVED; fix PRD if NEEDS_FIX |
+| /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 |
 | /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          | `/generate-tests {UC-ID}`                     |
+| /generate-code          | First gen → `/review-code {UC-ID}`; re-gen → `/generate-tests {UC-ID}` |
 | /generate-tests         | `/run-tests {UC-ID}`                          |
 | /run-tests (passing)    | `/review-code {UC-ID}`                        |
 | /run-tests (failing)    | `/fix-bug {ticket-id}` or `/debug {error}`    |
 | /review-code            | `/smoke-test {UC-ID}` or create PR            |
 | /smoke-test             | Create PR and link to ticket                  |
-| /validate-traces        | `/generate-code {UC-ID}` for gaps             |
+| /validate-traces        | DRIFT/UNTRACKED → `/generate-code {UC-ID}`; GAP → `/generate-tests {UC-ID}`; all OK → create PR |
 | /fix-bug                | Create PR and link to ticket                  |
 | /debug                  | `/fix-bug {ticket-id}` if fix needed          |
 
@@ -471,7 +529,7 @@ Next: Open in Review Board → Accept/Modify/Reject each finding
 ## Resume Mode — Apply Accepted Findings
 
 *Triggered when `$ARGUMENTS` contains `--resume`.*
-*Example: `/review-tech-docs --resume tech-docs/payment/PAY-UC1-tech-design.md`*
+*Example: `/review-tech-docs --resume {paths.tech_docs_dir}/payment/PAY-UC1-tech-design.md`*
 
 ### Phase 1 — Read accepted findings
 
@@ -494,10 +552,19 @@ Apply in order: critical → major → minor.
 **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 + Report
+### 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 — set its value to `draft`.
+
+Write both changes to the file.
+
+Then update `{paths.trace_dir}/{UC-ID}.tsv`:
+- Set `tech_doc_revision` column to the new `@trace.revision` integer for all rows of this UC.
+- Set `last_updated` to today's date (`YYYY-MM-DD`) for all rows of this UC.
 
-1. Increment `@trace.revision` in the tech-doc header by 1.
-2. Update `@trace.status` to `draft` (reset — must be re-approved after changes).
+Print the report after all file writes are complete.
 
 ```
 /review-tech-docs --resume Applied — {target file}

package/commands/review-tech-docs.tmpl

@@ -174,7 +174,7 @@ Next: Open in Review Board → Accept/Modify/Reject each finding
 ## Resume Mode — Apply Accepted Findings
 
 *Triggered when `$ARGUMENTS` contains `--resume`.*
-*Example: `/review-tech-docs --resume tech-docs/payment/PAY-UC1-tech-design.md`*
+*Example: `/review-tech-docs --resume {paths.tech_docs_dir}/payment/PAY-UC1-tech-design.md`*
 
 ### Phase 1 — Read accepted findings
 
@@ -197,10 +197,19 @@ Apply in order: critical → major → minor.
 **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 + Report
+### Phase 3 — Update header + TSV + Report
 
-1. Increment `@trace.revision` in the tech-doc header by 1.
-2. Update `@trace.status` to `draft` (reset — must be re-approved after changes).
+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 — set its value to `draft`.
+
+Write both changes to the file.
+
+Then update `{paths.trace_dir}/{UC-ID}.tsv`:
+- Set `tech_doc_revision` column to the new `@trace.revision` integer for all rows of this UC.
+- 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}

package/commands/run-tests.md

@@ -31,7 +31,7 @@ Display and wait for response:
 ```
 ⚙️  MODEL CHECK
 ──────────────────────────────────────────────────────────────────
-  Recommended  : claude-opus-4-5 (or claude-opus-4)
+  Recommended  : claude-opus-4 (or latest Opus model)
   Why needed   : Spec analysis, architecture review, code generation
                  require deep reasoning. Smaller models miss edge cases.
 
@@ -84,7 +84,7 @@ Wait for explicit "Y" or "N" from the user before continuing.
 - "N" → stop and ask what the user wants to change.
 
 
-*Note: For this command, the target in Step 1 is a UC-ID or service name from `$ARGUMENTS`. Context loading provides `conventions.test_command`.*
+*Note: For this command, the target in Step 1 is a UC-ID or service name. Context loading provides `conventions.test_command` and `tech_stack.module`.*
 
 ## Context
 # Context Loader — Load All Project Context
@@ -131,6 +131,7 @@ Read `.agent/project-context.yaml`. Extract and store:
 - `paths.core_entities` → path to core-entities.md
 - `paths.tech_docs_dir` → technical documentation root
 - `paths.trace_dir` → trace state directory
+- `paths.design_spec_dir` → Design Spec documents root (FE/App only)
 
 If `paths` section is absent, use these defaults:
 - `specs_dir` = `specs/bdd`
@@ -140,13 +141,46 @@ If `paths` section is absent, use these defaults:
 - `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` = `tech-docs`
+- `tech_docs_dir` = `specs/tech-docs`
 - `trace_dir` = `.trace`
+- `design_spec_dir` = `specs/design-spec`
 
 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: segment immediately after `prd_dir` base path  
+  *(e.g., `specs/prd/user/FEAT-01.md` → domain = `user`)*
+- If `$ARGUMENTS` contains a path, extract the segment after `prd_dir`
+
+**2. Route to service** — if active domain matches a key in `services`:
+- Override `paths.specs_dir` → `services.{domain}.specs_dir`
+- Override `paths.tech_docs_dir` → `services.{domain}.tech_docs_dir`
+- 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.prd_dir` → `{spec_source}/specs/prd`
+- Override `paths.design_spec_dir` → `{spec_source}/specs/design-spec`
+- 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`
+
+---
+
 ## Step 2 — [PROJECT-CONFIG] Load module stack profile (conditional)
 
 If `tech_stack.module` is set, read `.agent/modules/{module}/stack-profile.yaml`.
@@ -217,6 +251,26 @@ 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 (generate-tests, debug, fix-bug, smoke-test).
+
+---
+
 ## Step 7 — [RECAP] Working Memory Recap (anti-lost-in-middle)
 
 After loading all context, synthesize and output a compact summary block.
@@ -227,10 +281,12 @@ Output exactly this block:
 ```
 [CTX LOADED]
 Stack     : {language} / {framework} / {database}
+Platform  : {active_module} ({platform_type})
 Layers    : {layer order from CLAUDE.md §2, e.g., Controller → Facade → Service → Repository}
 Ticket    : {ticket_prefix}-
 Dict      : {loaded — N canonical terms, M banned terms | missing}
 Entities  : {loaded — EntityA, EntityB, EntityC | missing}
+Service   : {active_service} ({active_service_module}) | single-service
 Status    : {FULL | PARTIAL — missing: CLAUDE.md / business-dict / core-entities | MINIMAL}
 ```
 
@@ -252,25 +308,142 @@ After completing all steps, you have loaded:
 Proceed to the next step of the calling command.
 
 
+---
+
+## Service Detection
+
+Read `active_module` from context (resolved in context-loader Step 1).
+Use it to select the correct run command and error analysis table below.
+
 ---
 
 ## Run
+
+### If `platform_type = backend`
+
+```bash
+# Run all tests for this UC
+{conventions.test_command}
+
+# Scoped to specific class (faster feedback)
+# java-spring:
+mvn test -Dtest={ClassName}
+# golang:
+go test ./... -run Test{FunctionName}
+# dotnet:
+dotnet test --filter "FullyQualifiedName~{ClassName}"
+# php-laravel:
+php artisan test --filter {ClassName}
+# context-engineering (pytest):
+pytest tests/{domain}/{test_file}.py -v
+pytest tests/{domain}/{test_file}.py::{TestClass}::{test_method} -v
+pytest tests/ --cov={source_dir} --cov-report=term-missing
+```
+
+### If `platform_type = web-frontend`
+
 ```bash
-{conventions.test_command}                          # all tests in module
-{conventions.test_command} --class {ClassName}      # specific class (faster)
-{conventions.test_command} --pattern "*{Resource}*" # by pattern
+# Run all tests
+{conventions.test_command}
+
+# Scoped (Vitest / Jest):
+npx vitest run src/features/{domain}/{Component}.test.tsx
+npx jest src/features/{domain}/{Component}.test.tsx
+
+# E2E (Playwright):
+npx playwright test {UC-ID}
+# E2E (Cypress):
+npx cypress run --spec "cypress/e2e/{UC-ID}*"
 ```
 
+### If `platform_type = mobile`
+
+```bash
+# Flutter:
+flutter test test/{domain}/{UC-ID}_test.dart
+flutter test integration_test/{UC-ID}_test.dart   # integration
+
+# React Native:
+npx jest {UC-ID}
+
+# iOS (Xcode command line):
+xcodebuild test -scheme {Scheme} -destination 'platform=iOS Simulator,name=iPhone 15'
+
+# Android:
+./gradlew test                              # unit tests
+./gradlew connectedAndroidTest              # instrumented (device/emulator required)
+```
+
+> **Note for Android instrumented tests:** a running emulator or connected device is required before running `connectedAndroidTest`. Start one via Android Studio or: `emulator -avd {AVD_NAME} &`
+
+---
+
 ## Analyze Failures
 
+### Backend failure patterns
+
+#### java-spring / golang / dotnet / php-laravel
+
+| Error Pattern | Common Cause | Suggested Fix |
+|---|---|---|
+| `NullPointerException` | Missing mock setup | Check `given(...)`/`coEvery`/`mockk` for null dependency |
+| `Bean not found` | Missing mock declaration | Add `@MockBean` / inject mock |
+| `Expected 200, got 401` | Missing auth setup | Add auth token/user to test context |
+| `Expected 200, got 400` | Request body fails validation | Check required fields in DTO |
+| `Expected 200, got 403` | Wrong role | Add correct role to test user |
+| `LazyInitializationException` | Lazy collection outside transaction | Add `@Transactional` or eager fetch |
+| `Mapper not found` | Code not compiled | Run build step before tests |
+| `DataIntegrityViolationException` | Duplicate key in DB setup | Use `@Transactional` + rollback, or clean DB between tests |
+| Assertion mismatch | Wrong mock return value | Re-read `given(...).willReturn(...)` setup |
+
+#### context-engineering (AI/LLM pipelines)
+
 | Error Pattern | Common Cause | Suggested Fix |
 |---|---|---|
-| NullPointerException | Missing mock setup | Check `given(...)` for null dependency |
-| Bean not found | Missing mock declaration | Add mock for missing dependency |
-| Expected 200, got 403 | Missing auth setup | Add auth user/role to test context |
-| Expected 200, got 400 | Request body fails validation | Check required fields in DTO |
-| LazyInitializationException | Lazy collection outside transaction | Add `@Transactional` or eager fetch |
-| Mapper not found | Code generator not run | Run compile step before tests |
+| `AssertionError` on LLM mock output | Mock return value not matching schema | Re-check `mock_llm.return_value` / `mock_llm.complete.return_value` setup |
+| `ValidationError` on response | LLM output structure doesn't match expected schema | Tighten schema check or add retry logic in test |
+| `ConnectionError` / `APIError` | Real LLM API being called in test | Ensure `patch('...')` mock is applied — never call real LLM in unit tests |
+| `TimeoutError` | Test calling live LLM endpoint | Add mock; check test fixtures |
+| Flaky / non-deterministic results | Real LLM response used in assertion | Replace with deterministic mock return value |
+
+### Web frontend failure patterns
+
+| Error Pattern | Common Cause | Suggested Fix |
+|---|---|---|
+| `Unable to find role "..."` | Element not rendered yet | Wrap in `await waitFor(() => ...)` |
+| `TestingLibraryElementError: Found multiple elements` | Selector too broad | Use `getByRole(..., { name: '...' })` to narrow |
+| `Network request not intercepted` | Missing MSW handler / `cy.intercept` | Add handler for the endpoint |
+| `act(...)` warning | State update after test ended | Await async events / `await userEvent.click(...)` |
+| `Cannot read properties of undefined` | Component rendered before data loaded | Add loading state or mock resolved data |
+| Playwright timeout | Page not navigated / element hidden | Check route, add `waitForSelector` |
+| `expect(page.locator(...)).toBeVisible` fails | Wrong selector | Use Playwright Inspector to find correct locator |
+
+### Mobile failure patterns
+
+#### Flutter
+| Error Pattern | Common Cause | Suggested Fix |
+|---|---|---|
+| `pumpAndSettle timed out` | Async operation not completing | Use `pump(Duration(...))` for specific delay |
+| `No widget found` | Widget not rendered / wrong finder | Check `find.byType`, `find.text`, `find.byKey` |
+| `setState called after dispose` | Widget disposed before async completes | Cancel async in `dispose()` |
+| BLoC state mismatch | Wrong event emitted | Verify `mockBloc` received correct event |
+
+#### React Native
+| Error Pattern | Common Cause | Suggested Fix |
+|---|---|---|
+| `Unable to find element` | Missing `testID` or wrong query | Add `accessibilityLabel` or `testID` to component |
+| `act(...)` warning | Async state updates | Wrap in `act(async () => { ... })` |
+| Navigation mock missing | `useNavigation` not mocked | Add jest mock for `@react-navigation/native` |
+
+#### iOS / Android
+| Error Pattern | Common Cause | Suggested Fix |
+|---|---|---|
+| `XCTAssertEqual failed` | Wrong expected value | Check ViewModel output for given mock |
+| `Compose node not found` | Wrong `contentDescription` / `testTag` | Add `Modifier.testTag(...)` to composable |
+| `Hilt injection failed` | Missing test module | Add `@UninstallModules` + `@BindValue` in test class |
+| Emulator not available | `connectedAndroidTest` without device | Start emulator first, wait for it to boot |
+
+---
 
 ## Output
 
@@ -302,21 +475,23 @@ 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)   | `/generate-bdd {prd-file}` if APPROVED; fix PRD if NEEDS_FIX |
+| /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 |
 | /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          | `/generate-tests {UC-ID}`                     |
+| /generate-code          | First gen → `/review-code {UC-ID}`; re-gen → `/generate-tests {UC-ID}` |
 | /generate-tests         | `/run-tests {UC-ID}`                          |
 | /run-tests (passing)    | `/review-code {UC-ID}`                        |
 | /run-tests (failing)    | `/fix-bug {ticket-id}` or `/debug {error}`    |
 | /review-code            | `/smoke-test {UC-ID}` or create PR            |
 | /smoke-test             | Create PR and link to ticket                  |
-| /validate-traces        | `/generate-code {UC-ID}` for gaps             |
+| /validate-traces        | DRIFT/UNTRACKED → `/generate-code {UC-ID}`; GAP → `/generate-tests {UC-ID}`; all OK → create PR |
 | /fix-bug                | Create PR and link to ticket                  |
 | /debug                  | `/fix-bug {ticket-id}` if fix needed          |
 
@@ -330,14 +505,17 @@ Next   : {suggested command with example arguments}
 
 
 ```
-/run-tests Report — {service}
+/run-tests Report — {UC-ID} ({active_module})
 ✅ Passed: {N} | ❌ Failed: {M} | ⏭️ Skipped: {K} | Duration: {X}s
 
 ## Failed Tests
 | Test | Error | Root Cause |
-|------|-------|-----------|
+|------|-------|------------|
 
 ## Recommendations
 {specific fix per failure}
-Next: /fix-bug if real bug, or correct test if wrong expectation.
+
+Next:
+  All tests pass → /review-code {UC-ID}
+  Tests fail     → /fix-bug {TICKET_ID} (real bug) or fix test (wrong expectation)
 ```