@edupia-tutor/spec-driven-docs 0.14.0

package/commands/debug.tmpl

@@ -0,0 +1,257 @@
+# /debug — Quick Debug Analysis
+
+Use for: IDE errors, test failures, strange behavior, or "why does this code do X?"
+Different from `/fix-bug`: analysis only, no full workflow, no ticket needed.
+
+## Gate
+{{include:steps/gate.md}}
+
+*Note: For this command, the target in Step 1 is user-provided input (stack trace, test failure output, file path + description, or code question). No file discovery needed — go straight to context loading.*
+
+## Context
+{{include:steps/context-loader.md}}
+
+---
+
+## 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
+  at {class}.{method}({file}:{line})
+```
+
+## 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 / 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}
+  at {test}.{method}(line {N})
+```
+1. What is the gap? 2. Is mock setup correct? 3. Is assertion logically correct?
+
+---
+
+## Output
+
+{{include:steps/report-footer.md}}
+
+```
+/debug Analysis
+
+## Error
+{description}
+
+## Root Cause
+{technical explanation}
+
+## Location
+File: {path} | Line: {N} | Layer: {Controller/Service/Repository/Test}
+
+## Suggested Fix
+{specific code change}
+
+## Related Rule
+See CLAUDE.md §{section}
+
+## Next Step
+- To fully fix → /fix-bug {TICKET_ID}
+- Just needed analysis → done
+```
+
+---
+
+## Offer to Record a Lesson (optional)
+
+If the root cause is a **mistake the AI made when generating code and could repeat**
+(not an environment/config issue or external cause), ask:
+
+```
+This looks like a repeatable AI mistake. Record it as a project lesson? (Y/N)
+```
+
+If `Y` → run the capture procedure below with `source=/debug`, an appropriate `category`
+(usually `code-gen`), and `scope` = the affected domain or file glob.
+
+{{include:steps/capture-lesson.md}}