@anhth2/spec-driven-dev-plugin 0.5.0

package/bin/index.js

@@ -0,0 +1,311 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const ROOT = path.join(__dirname, '..');
+
+const pkg      = JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8'));
+const VERSION  = pkg.version;
+
+const args = process.argv.slice(2);
+const isInit     = args.includes('--init');
+const isProject  = args.includes('--project');
+const installHooks = args.includes('--hooks');
+const showHelp   = args.includes('--help') || args.includes('-h');
+
+// --module <name> flag
+const moduleIdx  = args.indexOf('--module');
+const moduleName = moduleIdx !== -1 ? args[moduleIdx + 1] : null;
+
+const AVAILABLE_MODULES = [
+  'java-spring', 'angular', 'react', 'nextjs',
+  'dotnet', 'golang', 'php-laravel', 'context-engineering',
+];
+
+if (showHelp) {
+  console.log('Usage: npx @anhth2/spec-driven-dev [options]');
+  console.log('');
+  console.log('Install modes:');
+  console.log('  --init             NEW: Install framework to .agent/ + create shortcuts in .claude/commands/');
+  console.log('                         Recommended for new projects. Run upgrade.sh to upgrade later.');
+  console.log('  --project          Install full commands to ./.claude/commands/ (project-scoped, legacy)');
+  console.log('  (no flag)          Install full commands to ~/.claude/commands/ (global, legacy)');
+  console.log('');
+  console.log('Options:');
+  console.log('  --module <name>    Copy stack module to .agent/modules/<name>/');
+  console.log('  --hooks            Install data-guard hook to .claude/hooks/ + update .claude/settings.json');
+  console.log('');
+  console.log('Available modules:');
+  AVAILABLE_MODULES.forEach(m => console.log(`  ${m}`));
+  console.log('');
+  console.log('Examples:');
+  console.log('  npx @anhth2/spec-driven-dev --init                         # new project setup');
+  console.log('  npx @anhth2/spec-driven-dev --init --module java-spring    # with stack module');
+  console.log('  npx @anhth2/spec-driven-dev --project --hooks              # legacy project install');
+  process.exit(0);
+}
+
+// ── Step 1: Build .tmpl → .md ─────────────────────────────────────────────
+const buildScript = path.join(__dirname, 'build.js');
+if (fs.existsSync(buildScript)) {
+  try {
+    require(buildScript);
+  } catch (err) {
+    console.error('Build step failed:', err.message);
+    process.exit(1);
+  }
+}
+
+// ── --init mode: install to .agent/ + create .claude/commands/ shortcuts ─────
+if (isInit) {
+  const coreDir = path.join(ROOT, 'core');
+
+  if (!fs.existsSync(coreDir)) {
+    console.error('');
+    console.error('❌ core/ directory not found.');
+    console.error('   The package may not have been built correctly.');
+    process.exit(1);
+  }
+
+  const projectRoot      = process.cwd();
+  const agentDir         = path.join(projectRoot, '.agent');
+  const claudeCommandsDir = path.join(projectRoot, '.claude', 'commands');
+  const frameworkVersion = fs.readFileSync(path.join(coreDir, 'FRAMEWORK_VERSION'), 'utf8').trim();
+
+  console.log('');
+  console.log('╔══════════════════════════════════════════╗');
+  console.log('║     Spec-Driven Dev — Project Init       ║');
+  console.log(`║     v${frameworkVersion}  (Edupia Team)                ║`);
+  console.log('╚══════════════════════════════════════════╝');
+  console.log('');
+  console.log(`Target : ${agentDir}`);
+  if (moduleName) console.log(`Module : ${moduleName}`);
+  console.log('');
+
+  // 1. Copy core/** → .agent/**
+  console.log('Installing framework files to .agent/ ...');
+  console.log('');
+  copyDirRecursive(coreDir, agentDir);
+
+  const agentSubdirs = fs.readdirSync(agentDir, { withFileTypes: true })
+    .filter(e => e.isDirectory())
+    .map(e => e.name);
+  for (const sub of agentSubdirs) {
+    console.log(`  ✅ .agent/${sub}/`);
+  }
+  console.log(`  ✅ .agent/FRAMEWORK_VERSION  (v${frameworkVersion})`);
+
+  // 2. Create .claude/commands/ shortcuts that delegate to .agent/commands/
+  console.log('');
+  console.log('Creating .claude/commands/ shortcuts ...');
+  console.log('');
+  fs.mkdirSync(claudeCommandsDir, { recursive: true });
+
+  const agentCommandsDir = path.join(agentDir, 'commands');
+  const commandFiles = fs.readdirSync(agentCommandsDir).filter(f => f.endsWith('.md'));
+  const failedShortcuts = [];
+
+  for (const cmdFile of commandFiles) {
+    const cmdName = cmdFile.replace('.md', '');
+    const shortcut =
+      `# /${cmdName}\n` +
+      `\n` +
+      `Read the full command definition from \`.agent/commands/${cmdFile}\`` +
+      ` and execute it with arguments: $ARGUMENTS\n`;
+    try {
+      fs.writeFileSync(path.join(claudeCommandsDir, cmdFile), shortcut, 'utf8');
+      console.log(`  ✅ /${cmdName}`);
+    } catch {
+      console.log(`  ❌ /${cmdName}  (failed to write shortcut)`);
+      failedShortcuts.push(cmdName);
+    }
+  }
+
+  // 3. Install module (optional --module flag)
+  if (moduleName) {
+    console.log('');
+    if (!AVAILABLE_MODULES.includes(moduleName)) {
+      console.log(`⚠️  Unknown module: "${moduleName}"`);
+      console.log(`   Available: ${AVAILABLE_MODULES.join(', ')}`);
+    } else {
+      const srcModuleDir  = path.join(ROOT, 'modules', moduleName);
+      const destModuleDir = path.join(agentDir, 'modules', moduleName);
+      fs.mkdirSync(destModuleDir, { recursive: true });
+      copyDirRecursive(srcModuleDir, destModuleDir);
+      console.log(`✅ Module "${moduleName}" installed to: .agent/modules/${moduleName}`);
+    }
+  }
+
+  // 4. Install data-guard hook (optional --hooks flag)
+  if (installHooks) {
+    console.log('');
+    installDataGuardHook();
+  }
+
+  // 5. Summary
+  console.log('');
+  if (failedShortcuts.length > 0) {
+    console.log(`⚠️  ${commandFiles.length - failedShortcuts.length}/${commandFiles.length} shortcuts created.`);
+    process.exit(1);
+  }
+  console.log(`✅ Framework v${frameworkVersion} installed!`);
+  console.log('');
+  console.log('Next steps:');
+  console.log('  1. Open Claude Code and run /setup-ai-first');
+  console.log('  2. Commit .agent/ to git so your whole team has the framework');
+  console.log('');
+  console.log('To upgrade later:  bash scripts/upgrade.sh');
+  console.log('                   (or: npx @anhth2/spec-driven-dev@latest --init)');
+  console.log('');
+  process.exit(0);
+}
+
+// ── Banner (legacy --project / global modes) ──────────────────────────────
+const targetDir = isProject
+  ? path.join(process.cwd(), '.claude', 'commands')
+  : path.join(os.homedir(), '.claude', 'commands');
+
+const scope = isProject ? 'project' : 'global';
+
+console.log('');
+console.log('╔══════════════════════════════════════════╗');
+console.log('║     Spec-Driven Dev — CLI Installer      ║');
+console.log(`║     v${VERSION}  (Edupia Team)                ║`);
+console.log('╚══════════════════════════════════════════╝');
+console.log('');
+console.log(`Scope  : ${scope}`);
+console.log(`Target : ${targetDir}`);
+if (moduleName)    console.log(`Module : ${moduleName}`);
+if (installHooks)  console.log('Hooks  : enabled');
+console.log('');
+
+// ── Step 2: Install commands ──────────────────────────────────────────────
+fs.mkdirSync(targetDir, { recursive: true });
+
+const commandsDir = path.join(ROOT, 'commands');
+const commands    = fs.readdirSync(commandsDir).filter(f => f.endsWith('.md'));
+const failed      = [];
+
+for (const cmd of commands) {
+  try {
+    fs.copyFileSync(path.join(commandsDir, cmd), path.join(targetDir, cmd));
+    console.log(`  ✅ ${cmd.replace('.md', '')}`);
+  } catch {
+    console.log(`  ❌ ${cmd.replace('.md', '')} (failed)`);
+    failed.push(cmd);
+  }
+}
+
+console.log('');
+
+if (failed.length > 0) {
+  console.log(`⚠️  Installed ${commands.length - failed.length}/${commands.length} commands. Failed: ${failed.join(', ')}`);
+  process.exit(1);
+}
+
+console.log(`✅ Installed ${commands.length}/${commands.length} commands to:`);
+console.log(`   ${targetDir}`);
+
+// ── Step 3: Install module (optional) ─────────────────────────────────────
+if (moduleName) {
+  console.log('');
+  if (!AVAILABLE_MODULES.includes(moduleName)) {
+    console.log(`⚠️  Unknown module: "${moduleName}"`);
+    console.log(`   Available: ${AVAILABLE_MODULES.join(', ')}`);
+    process.exit(1);
+  }
+
+  const srcModuleDir  = path.join(ROOT, 'modules', moduleName);
+  const destModuleDir = path.join(process.cwd(), '.agent', 'modules', moduleName);
+
+  fs.mkdirSync(destModuleDir, { recursive: true });
+  copyDirRecursive(srcModuleDir, destModuleDir);
+
+  console.log(`✅ Module "${moduleName}" installed to:`);
+  console.log(`   ${destModuleDir}`);
+}
+
+// ── Step 4: Install data-guard hook (optional, --hooks flag) ──────────────
+if (installHooks) {
+  console.log('');
+  installDataGuardHook();
+}
+
+// ── Summary ───────────────────────────────────────────────────────────────
+console.log('');
+console.log('Next steps:');
+console.log('  1. Open your project in Claude Code');
+console.log('  2. Type /setup-ai-first to initialize the workflow');
+console.log('  3. Type / to browse all available commands');
+if (!moduleName) {
+  console.log('');
+  console.log(`Tip: re-run with --module <name> to install a stack profile.`);
+  console.log(`     Available: ${AVAILABLE_MODULES.join(', ')}`);
+}
+if (!installHooks) {
+  console.log('');
+  console.log('Tip: re-run with --hooks to install data-guard hook (sensitive file protection).');
+}
+console.log('');
+
+// ── Helpers ───────────────────────────────────────────────────────────────
+
+function copyDirRecursive(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src)) {
+    const srcPath  = path.join(src, entry);
+    const destPath = path.join(dest, entry);
+    if (fs.statSync(srcPath).isDirectory()) {
+      copyDirRecursive(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+function installDataGuardHook() {
+  const projectRoot = process.cwd();
+  const hooksDir    = path.join(projectRoot, '.claude', 'hooks');
+  const settingsPath = path.join(projectRoot, '.claude', 'settings.json');
+
+  // 1. Copy hook script
+  fs.mkdirSync(hooksDir, { recursive: true });
+  const srcHook  = path.join(ROOT, 'hooks', 'data-guard.js');
+  const destHook = path.join(hooksDir, 'data-guard.js');
+  fs.copyFileSync(srcHook, destHook);
+  console.log(`  ✅ Hook copied to: .claude/hooks/data-guard.js`);
+
+  // 2. Update .claude/settings.json
+  let settings = {};
+  if (fs.existsSync(settingsPath)) {
+    try { settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8')); } catch {}
+  }
+
+  // Merge: add PreToolUse hook if not already present
+  if (!settings.hooks) settings.hooks = {};
+  if (!settings.hooks.PreToolUse) settings.hooks.PreToolUse = [];
+
+  const hookEntry = {
+    matcher: 'Read|Write|Edit|Bash',
+    hooks: [{ type: 'command', command: 'node .claude/hooks/data-guard.js' }],
+  };
+
+  const alreadyRegistered = settings.hooks.PreToolUse.some(
+    h => h.hooks && h.hooks.some(hh => hh.command && hh.command.includes('data-guard.js'))
+  );
+
+  if (!alreadyRegistered) {
+    settings.hooks.PreToolUse.push(hookEntry);
+    fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf8');
+    console.log(`  ✅ Hook registered in: .claude/settings.json`);
+  } else {
+    console.log(`  ℹ️  Hook already registered in .claude/settings.json`);
+  }
+
+  console.log('');
+  console.log('  🔒 Data guard active — AI will be blocked from reading:');
+  console.log('     .env*, *.key, *.pem, *secret*, *password*, *credential*');
+  console.log('     application-prod.*, appsettings.Production.json, ...');
+}

package/commands/debug.md

@@ -0,0 +1,374 @@
+# /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
+# 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-5 (or claude-opus-4)
+  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 UC-ID, ticket ID, or partial name → search for matching files in the relevant directory.
+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 user-provided input (stack trace, test failure output, file path + description, or code question). No file discovery needed — go straight to context loading.*
+
+## 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` → BDD specs root
+- `paths.prd_dir` → PRD documents root
+- `paths.refinement_dir` → findings/review output dir
+- `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
+- `paths.trace_dir` → trace state directory
+
+If `paths` section is absent, use these defaults:
+- `specs_dir` = `specs/bdd`
+- `prd_dir` = `specs/prd`
+- `refinement_dir` = `.agent/review`
+- `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` = `tech-docs`
+- `trace_dir` = `.trace`
+
+If `tech_stack.module` is set, also load `.agent/modules/{module}/stack-profile.yaml` if it exists.
+
+---
+
+## 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
+
+*This is the highest-priority context — it defines HOW to write code and documents for this project.*
+
+Read `CLAUDE.md`. 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
+- **§3 Coding Standards** → naming conventions (classes, methods), response wrapper type, forbidden patterns
+- **§5 Error Handling** → exception types, HTTP status code mapping, not-found exception class name
+- **§7 Git Conventions** → branch naming pattern, commit message format
+
+If `CLAUDE.md` does not exist → note it 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 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}
+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}
+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.
+
+
+---
+
+## 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
+
+## 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
+
+| 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 |
+| 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 |
+
+## 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
+
+# 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)`.
+
+## Next Command Suggestion
+
+Suggest the logical next command based on workflow phase:
+
+| Current command         | Suggest next                                  |
+|-------------------------|-----------------------------------------------|
+| /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 |
+| /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-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             |
+| /fix-bug                | Create PR and link to ticket                  |
+| /debug                  | `/fix-bug {ticket-id}` if fix needed          |
+
+Format the footer as:
+```
+---
+Status : {badge}
+{Output Artifacts block}
+Next   : {suggested command with example arguments}
+```
+
+
+```
+/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
+```