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

package/commands/debug.tmpl

@@ -13,13 +13,112 @@ Different from `/fix-bug`: analysis only, no full workflow, no ticket needed.
 
 ---
 
-## Input — Paste one of:
-1. Stack trace / error log
-2. Test failure output
-3. File path + description of unexpected behavior
-4. A specific question about a code snippet
+## Step 1 — Classify debug type
+
+After loading context, display this prompt and wait for the user's choice:
+
+```
+DEBUG SESSION
+──────────────────────────────────────────────────────────────
+  What's your situation?
+
+  1  I already have a stack trace / error log  → paste it
+  2  I need to reproduce the error first       → show me the run command
+  3  A test is failing                         → I'll run tests, then paste output
+  4  Code question (no runtime needed)         → ask away
+──────────────────────────────────────────────────────────────
+Enter 1 / 2 / 3 / 4:
+```
+
+Wait for the user's choice, then follow the corresponding path below.
+
+---
+
+### Path 1 — Already have error output
+
+Ask:
+```
+Paste your stack trace / error log below:
+```
+
+Wait for input, then proceed to [Stack Trace Analysis](#stack-trace-analysis).
+
+---
+
+### Path 2 — Need to reproduce first
+
+Display the run command from `conventions.service_run` in `project-context.yaml`:
+
+```
+Start your service first:
+
+  {conventions.service_run}
+
+(If you use Docker: `docker compose up -d`, then verify with `docker compose ps`)
+
+Once the service is running:
+  1. Trigger the behavior that causes the error
+  2. Copy the full stack trace or error log
+  3. Paste it here
+
+Waiting for your error output...
+```
+
+Wait for the user to paste the error, then proceed to [Stack Trace Analysis](#stack-trace-analysis).
+
+If `conventions.service_run` is not set → show:
+```
+⚠️  service_run is not configured in .agent/project-context.yaml.
+    Add it so this command can show the correct start command:
+
+    conventions:
+      service_run: "mvn spring-boot:run"   # or: npm run dev / go run . / etc.
+```
+Then ask the user to start the service manually and paste the error when ready.
+
+---
+
+### Path 3 — Test is failing
+
+Display the test command from `conventions.test_command` in `project-context.yaml`:
+
+```
+Run your tests first:
+
+  {conventions.test_command}
+
+Once the run finishes, paste the full test failure output here.
+
+Waiting...
+```
+
+Wait for the user to paste the failure output, then proceed to [Test Failure Analysis](#test-failure-analysis).
+
+If `conventions.test_command` is not set → show:
+```
+⚠️  test_command is not configured in .agent/project-context.yaml.
+    Add it so this command can show the correct test command:
+
+    conventions:
+      test_command: "mvn test"   # or: npm test / go test ./... / etc.
+```
+Then ask the user to run tests manually and paste the output when ready.
+
+---
+
+### Path 4 — Code question
+
+Ask:
+```
+Describe your question or paste the code snippet you're asking about:
+```
+
+Wait for input, then answer directly using loaded project context (architecture rules, layer order, coding standards from CLAUDE.md).
+
+---
 
 ## Stack Trace Analysis
+
 Read from **bottom up** — `Caused by:` is the real root cause:
 ```
 Caused by: {RealException}  ← start here
@@ -28,20 +127,83 @@ Caused by: {RealException}  ← start here
 
 ## Common Error Patterns
 
+Use `active_module` from context to select the relevant table.
+
+### If `platform_type = backend`
+
+#### java-spring / golang / dotnet / php-laravel
+
 | Error | Likely Cause | Fix Direction |
 |-------|-------------|---------------|
 | NullPointerException | Null object access; Optional not handled | Check Optional.orElseThrow, null guards |
 | ClassCastException | Wrong type assumption | Check type at assignment/return |
 | OutOfMemoryError | Loading too much data | Add pagination |
 | StackOverflowError | Infinite recursion | Find recursive call with no base case |
-| Connection refused | Dependency not running | Check config URLs |
+| Connection refused | Dependency not running | Check config URLs / start service |
 | 401 Unauthorized | Token expired, wrong config | Verify token, check auth config |
 | 403 Forbidden | Wrong role | Check auth annotations |
 | DB constraint violation | Duplicate key, null in NOT NULL | Check data and constraints |
 | Serialization error | Circular reference | Check DTO/mapper config |
 | Test assertion mismatch | Wrong mock or wrong expected | Re-read mock setup |
 
+#### context-engineering (AI/LLM pipelines)
+
+| Error | Likely Cause | Fix Direction |
+|-------|-------------|---------------|
+| `APIError` / `RateLimitError` | LLM quota exceeded or service down | Check API key, rate limits; add exponential backoff |
+| `TokenLimitError` / `context_length_exceeded` | Input prompt too long | Truncate/chunk input; review prompt template size |
+| `AuthenticationError` | API key invalid or expired | Check env var; rotate key |
+| Response validation / schema mismatch | LLM output doesn't match expected format | Add output parser; retry with stricter prompt |
+| `JSONDecodeError` on LLM output | Model returned non-JSON text | Add JSON extraction post-processing or stricter system prompt |
+| Hanging / slow test | Real LLM called in test instead of mock | Verify `patch('...')` applied; add timeout guard |
+| Flaky results across runs | Non-deterministic LLM response | Use fixed mock in tests; check temperature = 0 for determinism |
+
+### If `platform_type = web-frontend`
+
+| Error | Likely Cause | Fix Direction |
+|-------|-------------|---------------|
+| `Cannot read properties of undefined` | Data not loaded yet | Add loading guard / optional chaining `?.` |
+| `useEffect` infinite loop | Dependency array wrong | Review deps, use stable refs / `useCallback` |
+| `Cannot update state on unmounted component` | Async resolves after unmount | Cancel in cleanup / use AbortController |
+| CORS error | API not configured | Check backend CORS config or dev proxy setup |
+| 401 Unauthorized | Token expired or missing | Refresh token / check Authorization header |
+| White screen / no output | Unhandled render error | Check browser console, add ErrorBoundary |
+| Type error (Zod / TypeScript) | API response shape mismatch | Compare actual response vs type definition |
+| `act(...)` warning in test | Async state update | Wrap in `act(async () => {...})` |
+| Module not found | Import path wrong | Check relative path / tsconfig alias |
+
+### If `platform_type = mobile`
+
+#### Flutter
+| Error | Likely Cause | Fix Direction |
+|-------|-------------|---------------|
+| `Null check operator on null value` | Nullable not guarded | Add `?` or null check before `!` |
+| `pumpAndSettle timed out` | Async not completing in test | Use `pump(Duration(...))` |
+| `setState called after dispose` | Async continues after widget removed | Cancel in `dispose()` |
+| `RenderFlex overflow` | Widget too wide for screen | Wrap with `Flexible`, `Expanded`, or `SingleChildScrollView` |
+| BLoC state not updating | Event not dispatched | Verify `bloc.add(Event())` is called |
+| `MissingPluginException` | Native plugin not linked | Run `flutter clean && flutter pub get` |
+
+#### React Native
+| Error | Likely Cause | Fix Direction |
+|-------|-------------|---------------|
+| `undefined is not an object` | Null prop access | Add null check / optional chaining |
+| Metro bundler error | Cache stale | `npx react-native start --reset-cache` |
+| `VirtualizedLists nested` | FlatList inside ScrollView | Use `nestedScrollEnabled` or restructure |
+| Navigation `undefined` | `useNavigation` outside navigator | Wrap component inside correct navigator |
+| `act(...)` warning | Async state update in test | Wrap in `act(async () => {...})` |
+
+#### iOS / Android
+| Error | Likely Cause | Fix Direction |
+|-------|-------------|---------------|
+| `SIGABRT` / `EXC_BAD_ACCESS` (iOS) | Nil dereference | Add optional binding `if let` / `guard let` |
+| `IllegalStateException` (Android) | Lifecycle violation | Check if fragment/activity still attached |
+| `NetworkOnMainThreadException` | Network call on UI thread | Move to coroutine / background thread |
+| Build fails after pod install | Pod cache stale | `pod deintegrate && pod install` |
+| `Hilt injection failed` | Missing `@AndroidEntryPoint` | Add annotation to Activity/Fragment |
+
 ## Test Failure Analysis
+
 ```
 Expected: {value}
 Actual  : {value}
@@ -49,6 +211,8 @@ Actual  : {value}
 ```
 1. What is the gap? 2. Is mock setup correct? 3. Is assertion logically correct?
 
+---
+
 ## Output
 
 {{include:steps/report-footer.md}}

package/commands/define-product.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.
 
@@ -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}
 ```
 
@@ -269,6 +325,8 @@ AI scans the project and writes:
 | {original}       | {canonical}                          |
 ```
 
+Store this terminology map in the output product-definition file under a `## Terminology Map` section — `/generate-prd` will reference it during its Terminology Rules step to ensure consistency.
+
 ---
 
 ## Phase 1 — Feature Definition *(CHECKPOINT 1)*
@@ -305,7 +363,7 @@ Confirm → write `✅ PO Confirmed: Yes` → proceed.
 
 ---
 
-## Phase 3 — Clarification Log
+## Phase 3 — Clarification Log *(CHECKPOINT 3)*
 
 Based on Phases 1-2, AI identifies gaps and asks follow-up questions. Continue rounds until no Unresolved Items remain.
 
@@ -321,6 +379,8 @@ Based on Phases 1-2, AI identifies gaps and asks follow-up questions. Continue r
 ### Unresolved Items
 - {item — or "None"}
 
+When all Unresolved Items are resolved → write `✅ CHECKPOINT 3: No Unresolved Items` → proceed to Phase 4.
+
 ---
 
 ## Phase 4 — Business Rules *(CHECKPOINT 4)*
@@ -417,21 +477,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          |
 

package/commands/define-product.tmpl

@@ -25,6 +25,8 @@ AI scans the project and writes:
 | {original}       | {canonical}                          |
 ```
 
+Store this terminology map in the output product-definition file under a `## Terminology Map` section — `/generate-prd` will reference it during its Terminology Rules step to ensure consistency.
+
 ---
 
 ## Phase 1 — Feature Definition *(CHECKPOINT 1)*
@@ -61,7 +63,7 @@ Confirm → write `✅ PO Confirmed: Yes` → proceed.
 
 ---
 
-## Phase 3 — Clarification Log
+## Phase 3 — Clarification Log *(CHECKPOINT 3)*
 
 Based on Phases 1-2, AI identifies gaps and asks follow-up questions. Continue rounds until no Unresolved Items remain.
 
@@ -77,6 +79,8 @@ Based on Phases 1-2, AI identifies gaps and asks follow-up questions. Continue r
 ### Unresolved Items
 - {item — or "None"}
 
+When all Unresolved Items are resolved → write `✅ CHECKPOINT 3: No Unresolved Items` → proceed to Phase 4.
+
 ---
 
 ## Phase 4 — Business Rules *(CHECKPOINT 4)*

package/commands/fix-bug.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.
 
@@ -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}
 ```
 
@@ -264,17 +320,59 @@ If no ticket — CHECKPOINT:
 
 ## Phase 2 — Root Cause Analysis
 
+Use `active_module` from context to select the relevant table.
+
+### If `platform_type = backend`
+
+#### java-spring / golang / dotnet / php-laravel
+
 | Bug Type | Common Location | How to Check |
 |----------|----------------|--------------|
 | Wrong response data | Mapping layer | Check field mapping, DTO conversions |
-| 400 Bad Request | Input validation | Check DTO constraints |
+| 400 Bad Request | Input validation | Check DTO constraints / validators |
+| 401 Unauthorized | Auth filter | Check token config, filter order |
 | 403 Forbidden | Auth config | Check role-based access rules |
 | 404 Not Found | Repository query | Check find method, ID types |
-| N+1 Query | Data access | Check for missing JOIN FETCH |
-| Null Pointer | Optional not handled | Check Optional.orElseThrow |
-| Transaction rollback | Missing @Transactional | Check transaction scope |
-| Stale cache | Missing cache eviction | Check cache invalidation |
-| Type mismatch in query | Filter/specification | Check field types in predicates |
+| N+1 Query | Data access | Check for missing JOIN FETCH / eager load |
+| Null Pointer | Optional not handled | Check Optional.orElseThrow, null guards |
+| Transaction rollback | Missing @Transactional | Check transaction scope, propagation |
+| Stale cache | Missing eviction | Check cache invalidation triggers |
+| Type mismatch | Filter / specification | Check field types in predicates |
+
+#### context-engineering (AI/LLM pipelines)
+
+| Bug Type | Common Location | How to Check |
+|----------|----------------|--------------|
+| Wrong pipeline output | Prompt template | Check prompt content; verify variables are substituted correctly |
+| Missing context in output | Context assembly | Verify all required context blocks are included and non-empty |
+| Schema validation failure | Output parser | Compare raw LLM output vs expected schema; add stricter output instructions |
+| Flaky / non-deterministic results | LLM temperature | Check temperature setting; use fixed seed/mock in tests |
+| API rate limit errors | LLM client | Implement backoff; check quota usage in provider dashboard |
+| Token limit exceeded | Prompt assembly | Reduce context size; add chunking strategy |
+
+### If `platform_type = web-frontend`
+
+| Bug Type | Common Location | How to Check |
+|----------|----------------|--------------|
+| Wrong data displayed | State / store | Check state update logic, selector |
+| UI not re-rendering | Missing reactive dep | Check deps array, state immutability |
+| API data not loading | HTTP client / hook | Check network tab, error handler |
+| 401 on API call | Auth token | Check token refresh, header injection |
+| Form not submitting | Validation / handler | Check form state, required fields, errors |
+| Route not found | Router config | Check route definition, lazy import |
+| Build / type error | TypeScript types | Compare type definitions vs actual API shape |
+
+### If `platform_type = mobile`
+
+| Bug Type | Common Location | How to Check |
+|----------|----------------|--------------|
+| Screen shows stale data | State / BLoC / ViewModel | Check event dispatched, state emitted correctly |
+| Crash on navigation | Route param missing | Check params passed, null safety |
+| API call not firing | Repository / service layer | Add log in repo method, check network |
+| UI not reflecting state | Widget not observing stream | Check `BlocBuilder` / `StateObserver` setup |
+| Crash on app resume | Lifecycle handler | Check `onResume` / `viewDidAppear` logic |
+| Auth token expired | Token refresh logic | Check refresh flow, token storage |
+| Permission denied | OS permission | Check runtime permission request code |
 
 CHECKPOINT — Root Cause Report:
 ```
@@ -342,21 +440,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          |
 

package/commands/fix-bug.tmpl

@@ -20,17 +20,59 @@ If no ticket — CHECKPOINT:
 
 ## Phase 2 — Root Cause Analysis
 
+Use `active_module` from context to select the relevant table.
+
+### If `platform_type = backend`
+
+#### java-spring / golang / dotnet / php-laravel
+
 | Bug Type | Common Location | How to Check |
 |----------|----------------|--------------|
 | Wrong response data | Mapping layer | Check field mapping, DTO conversions |
-| 400 Bad Request | Input validation | Check DTO constraints |
+| 400 Bad Request | Input validation | Check DTO constraints / validators |
+| 401 Unauthorized | Auth filter | Check token config, filter order |
 | 403 Forbidden | Auth config | Check role-based access rules |
 | 404 Not Found | Repository query | Check find method, ID types |
-| N+1 Query | Data access | Check for missing JOIN FETCH |
-| Null Pointer | Optional not handled | Check Optional.orElseThrow |
-| Transaction rollback | Missing @Transactional | Check transaction scope |
-| Stale cache | Missing cache eviction | Check cache invalidation |
-| Type mismatch in query | Filter/specification | Check field types in predicates |
+| N+1 Query | Data access | Check for missing JOIN FETCH / eager load |
+| Null Pointer | Optional not handled | Check Optional.orElseThrow, null guards |
+| Transaction rollback | Missing @Transactional | Check transaction scope, propagation |
+| Stale cache | Missing eviction | Check cache invalidation triggers |
+| Type mismatch | Filter / specification | Check field types in predicates |
+
+#### context-engineering (AI/LLM pipelines)
+
+| Bug Type | Common Location | How to Check |
+|----------|----------------|--------------|
+| Wrong pipeline output | Prompt template | Check prompt content; verify variables are substituted correctly |
+| Missing context in output | Context assembly | Verify all required context blocks are included and non-empty |
+| Schema validation failure | Output parser | Compare raw LLM output vs expected schema; add stricter output instructions |
+| Flaky / non-deterministic results | LLM temperature | Check temperature setting; use fixed seed/mock in tests |
+| API rate limit errors | LLM client | Implement backoff; check quota usage in provider dashboard |
+| Token limit exceeded | Prompt assembly | Reduce context size; add chunking strategy |
+
+### If `platform_type = web-frontend`
+
+| Bug Type | Common Location | How to Check |
+|----------|----------------|--------------|
+| Wrong data displayed | State / store | Check state update logic, selector |
+| UI not re-rendering | Missing reactive dep | Check deps array, state immutability |
+| API data not loading | HTTP client / hook | Check network tab, error handler |
+| 401 on API call | Auth token | Check token refresh, header injection |
+| Form not submitting | Validation / handler | Check form state, required fields, errors |
+| Route not found | Router config | Check route definition, lazy import |
+| Build / type error | TypeScript types | Compare type definitions vs actual API shape |
+
+### If `platform_type = mobile`
+
+| Bug Type | Common Location | How to Check |
+|----------|----------------|--------------|
+| Screen shows stale data | State / BLoC / ViewModel | Check event dispatched, state emitted correctly |
+| Crash on navigation | Route param missing | Check params passed, null safety |
+| API call not firing | Repository / service layer | Add log in repo method, check network |
+| UI not reflecting state | Widget not observing stream | Check `BlocBuilder` / `StateObserver` setup |
+| Crash on app resume | Lifecycle handler | Check `onResume` / `viewDidAppear` logic |
+| Auth token expired | Token refresh logic | Check refresh flow, token storage |
+| Permission denied | OS permission | Check runtime permission request code |
 
 CHECKPOINT — Root Cause Report:
 ```