devflow-kit 0.3.2 → 0.4.0

package/src/claude/agents/devflow/release.md

@@ -760,9 +760,266 @@ fi
 echo ""
 ```
 
-## Step 13: Final Summary
+## Step 13: Save Release Notes
 
-Provide release summary:
+Save comprehensive release notes to `.docs/releases/`:
+
+```bash
+# Create releases directory if it doesn't exist
+mkdir -p .docs/releases
+
+# Get current date
+RELEASE_DATE=$(date +%Y-%m-%d)
+
+# Generate release notes file
+RELEASE_NOTES_FILE=".docs/releases/RELEASE_NOTES_v${NEW_VERSION}.md"
+
+# Write comprehensive release notes
+cat > "$RELEASE_NOTES_FILE" <<EOF
+# Release ${NEW_VERSION}
+
+**Release Date:** ${RELEASE_DATE}
+**Previous Version:** ${CURRENT_VERSION}
+**Project Type:** ${PROJECT_TYPE}
+
+---
+
+## Release Summary
+
+- **Version bump:** ${CURRENT_VERSION} → ${NEW_VERSION}
+- **Commits included:** $(git rev-list --count $COMMIT_RANGE 2>/dev/null || echo "N/A")
+- **Release type:** ${BUMP_TYPE}
+- **Tag:** ${TAG_NAME}
+
+---
+
+## Changes
+
+$(cat <<'CHANGES_EOF'
+${CHANGELOG_ENTRY}
+CHANGES_EOF
+)
+
+---
+
+## Commit History
+
+\`\`\`
+$(git log --oneline $COMMIT_RANGE 2>/dev/null || echo "No commits to display")
+\`\`\`
+
+---
+
+## Build & Test Results
+
+- **Build:** ${BUILD_RESULT:-N/A}
+- **Tests:** ${TEST_RESULT:-N/A}
+
+---
+
+## Distribution
+
+EOF
+
+# Add registry links based on project type
+if [ -n "$PUBLISH_CMD" ] && [ "$PUBLISH_CMD" != "echo"* ]; then
+    echo "**Published to:**" >> "$RELEASE_NOTES_FILE"
+    case "$PROJECT_TYPE" in
+        nodejs)
+            PACKAGE_NAME=$(command -v jq >/dev/null && jq -r '.name' package.json 2>/dev/null || echo "unknown")
+            echo "- npm: https://www.npmjs.com/package/${PACKAGE_NAME}/v/${NEW_VERSION}" >> "$RELEASE_NOTES_FILE"
+            ;;
+        rust)
+            CRATE_NAME=$(grep '^name = ' Cargo.toml | head -1 | sed 's/name = "\(.*\)"/\1/')
+            echo "- crates.io: https://crates.io/crates/${CRATE_NAME}/${NEW_VERSION}" >> "$RELEASE_NOTES_FILE"
+            ;;
+        python)
+            PACKAGE_NAME=$(grep '^name = ' pyproject.toml | head -1 | sed 's/name = "\(.*\)"/\1/' || echo "unknown")
+            echo "- PyPI: https://pypi.org/project/${PACKAGE_NAME}/${NEW_VERSION}/" >> "$RELEASE_NOTES_FILE"
+            ;;
+        ruby)
+            GEM_NAME=$(ls *.gemspec 2>/dev/null | head -1 | sed 's/\.gemspec$//')
+            echo "- RubyGems: https://rubygems.org/gems/${GEM_NAME}/versions/${NEW_VERSION}" >> "$RELEASE_NOTES_FILE"
+            ;;
+        *) echo "- Package registry (check project documentation)" >> "$RELEASE_NOTES_FILE" ;;
+    esac
+    echo "" >> "$RELEASE_NOTES_FILE"
+fi
+
+# Add Git platform links
+if command -v gh >/dev/null && git remote get-url origin 2>/dev/null | grep -q "github.com"; then
+    REPO_URL=$(git remote get-url origin | sed 's/\.git$//')
+    cat >> "$RELEASE_NOTES_FILE" <<EOF
+
+**Git Repository:**
+- Release: ${REPO_URL}/releases/tag/${TAG_NAME}
+- Commits: ${REPO_URL}/compare/${LAST_TAG}...${TAG_NAME}
+- Changelog: ${REPO_URL}/blob/main/${CHANGELOG_FILE}
+
+EOF
+fi
+
+# Add verification steps
+cat >> "$RELEASE_NOTES_FILE" <<'EOF'
+
+---
+
+## Verification Steps
+
+1. **Registry Check:** Verify package appears in registry (may take a few minutes)
+2. **Fresh Install:** Test installation in a clean environment
+3. **Smoke Tests:** Run basic functionality tests
+4. **Documentation:** Update any version-specific documentation
+
+---
+
+*Release notes generated by DevFlow release agent*
+EOF
+
+echo ""
+echo "✅ Release notes saved to: $RELEASE_NOTES_FILE"
+echo ""
+```
+
+## Step 14: Verify Documentation Alignment
+
+Check and update documentation files to ensure consistency:
+
+```bash
+echo "📚 Verifying documentation alignment..."
+echo ""
+
+DOC_ISSUES=()
+
+# Check if ROADMAP.md exists and needs updating
+if [ -f "ROADMAP.md" ]; then
+    echo "Checking ROADMAP.md alignment..."
+
+    # Check if this release includes features that should be marked as completed
+    if echo "$CHANGELOG_ENTRY" | grep -qiE "(feat|feature|add|new)"; then
+        echo "⚠️  ROADMAP UPDATE NEEDED:"
+        echo "   This release includes new features."
+        echo "   Review ROADMAP.md and mark completed items."
+        echo "   File: ROADMAP.md"
+        echo ""
+        DOC_ISSUES+=("ROADMAP.md needs review for completed features")
+    fi
+
+    # Check if roadmap references old version
+    if grep -q "$CURRENT_VERSION" ROADMAP.md 2>/dev/null; then
+        echo "⚠️  ROADMAP VERSION REFERENCE:"
+        echo "   ROADMAP.md references old version $CURRENT_VERSION"
+        echo "   Consider updating version references to $NEW_VERSION"
+        echo ""
+        DOC_ISSUES+=("ROADMAP.md has old version references")
+    fi
+fi
+
+# Check for README.md files in subpackages (monorepo support)
+echo "Checking README.md files..."
+
+# Find all README.md files (excluding node_modules, .git, etc.)
+READMES=$(find . -name "README.md" -not -path "*/node_modules/*" -not -path "*/.git/*" -not -path "*/dist/*" -not -path "*/build/*" 2>/dev/null)
+
+if [ $(echo "$READMES" | wc -l) -gt 1 ]; then
+    echo "Found multiple README.md files (monorepo detected)"
+
+    # Check each README for version references
+    for readme in $READMES; do
+        if grep -q "$CURRENT_VERSION" "$readme" 2>/dev/null; then
+            echo "⚠️  VERSION MISMATCH: $readme"
+            echo "   Contains old version reference: $CURRENT_VERSION"
+            echo "   Should be updated to: $NEW_VERSION"
+            echo ""
+            DOC_ISSUES+=("$readme has old version reference")
+        fi
+    done
+
+    # Check for installation instructions consistency
+    MAIN_README="./README.md"
+    if [ -f "$MAIN_README" ]; then
+        MAIN_INSTALL=$(grep -A 3 "Installation\|Install\|Getting Started" "$MAIN_README" 2>/dev/null | head -5)
+
+        for readme in $READMES; do
+            if [ "$readme" != "$MAIN_README" ]; then
+                SUB_INSTALL=$(grep -A 3 "Installation\|Install\|Getting Started" "$readme" 2>/dev/null | head -5)
+
+                # Simple check if installation sections differ significantly
+                if [ -n "$MAIN_INSTALL" ] && [ -n "$SUB_INSTALL" ]; then
+                    if ! echo "$SUB_INSTALL" | grep -qF "$(echo "$MAIN_INSTALL" | head -1)"; then
+                        echo "⚠️  INSTALLATION INCONSISTENCY:"
+                        echo "   $readme has different installation instructions"
+                        echo "   than main README.md"
+                        echo ""
+                        DOC_ISSUES+=("$readme installation instructions differ from main README")
+                    fi
+                fi
+            fi
+        done
+    fi
+fi
+
+# Verify CHANGELOG.md is up to date
+if [ -f "$CHANGELOG_FILE" ]; then
+    if ! grep -q "## \[${NEW_VERSION}\]" "$CHANGELOG_FILE" 2>/dev/null; then
+        echo "❌ CHANGELOG MISSING NEW VERSION:"
+        echo "   $CHANGELOG_FILE does not contain entry for $NEW_VERSION"
+        echo "   This should have been added in Step 5"
+        echo ""
+        DOC_ISSUES+=("CHANGELOG missing $NEW_VERSION entry")
+    else
+        echo "✓ CHANGELOG contains $NEW_VERSION entry"
+    fi
+
+    # Check if changelog has link reference for new version
+    if ! grep -q "\[${NEW_VERSION}\].*http" "$CHANGELOG_FILE" 2>/dev/null; then
+        echo "⚠️  CHANGELOG LINK MISSING:"
+        echo "   $CHANGELOG_FILE missing link reference for $NEW_VERSION"
+        echo "   Add: [${NEW_VERSION}]: https://github.com/.../releases/tag/v${NEW_VERSION}"
+        echo ""
+        DOC_ISSUES+=("CHANGELOG missing link reference for $NEW_VERSION")
+    fi
+fi
+
+# Check for docs/ or documentation/ directories
+for docs_dir in "docs" "documentation" ".docs"; do
+    if [ -d "$docs_dir" ]; then
+        echo "Checking $docs_dir/ for version references..."
+
+        # Look for markdown files with old version
+        OLD_VERSION_DOCS=$(grep -rl "$CURRENT_VERSION" "$docs_dir" 2>/dev/null | grep -E "\.(md|markdown|txt)$" || true)
+
+        if [ -n "$OLD_VERSION_DOCS" ]; then
+            echo "⚠️  DOCUMENTATION VERSION REFERENCES:"
+            echo "$OLD_VERSION_DOCS" | while read -r doc_file; do
+                echo "   - $doc_file"
+            done
+            echo ""
+            DOC_ISSUES+=("Documentation files in $docs_dir/ have old version references")
+        fi
+    fi
+done
+
+# Summary of documentation issues
+echo ""
+if [ ${#DOC_ISSUES[@]} -eq 0 ]; then
+    echo "✅ All documentation checks passed"
+else
+    echo "⚠️  DOCUMENTATION ISSUES FOUND (${#DOC_ISSUES[@]}):"
+    for issue in "${DOC_ISSUES[@]}"; do
+        echo "   - $issue"
+    done
+    echo ""
+    echo "These issues should be addressed before announcing the release."
+    echo "Run a search-and-replace for version references:"
+    echo "   find . -type f -name '*.md' -exec sed -i 's/$CURRENT_VERSION/$NEW_VERSION/g' {} +"
+    echo ""
+fi
+```
+
+## Step 15: Final Summary
+
+Display release summary to console:
 
 ```bash
 echo "========================================="
@@ -773,15 +1030,22 @@ echo "📊 RELEASE SUMMARY:"
 echo "- Old version: $CURRENT_VERSION"
 echo "- New version: $NEW_VERSION"
 echo "- Project type: $PROJECT_TYPE"
-echo "- Commits included: $(git rev-list --count $COMMIT_RANGE)"
+echo "- Commits included: $(git rev-list --count $COMMIT_RANGE 2>/dev/null || echo "N/A")"
 echo "- Tag: $TAG_NAME"
+echo "- Release notes: .docs/releases/RELEASE_NOTES_v${NEW_VERSION}.md"
 echo ""
 
 if [ -n "$PUBLISH_CMD" ] && [ "$PUBLISH_CMD" != "echo"* ]; then
     echo "📦 PUBLISHED TO:"
     case "$PROJECT_TYPE" in
-        nodejs) echo "- npm: https://www.npmjs.com/package/<package-name>" ;;
-        rust) echo "- crates.io: https://crates.io/crates/<crate-name>" ;;
+        nodejs)
+            PACKAGE_NAME=$(command -v jq >/dev/null && jq -r '.name' package.json 2>/dev/null || echo "package")
+            echo "- npm: https://www.npmjs.com/package/${PACKAGE_NAME}"
+            ;;
+        rust)
+            CRATE_NAME=$(grep '^name = ' Cargo.toml | head -1 | sed 's/name = "\(.*\)"/\1/')
+            echo "- crates.io: https://crates.io/crates/${CRATE_NAME}"
+            ;;
         python) echo "- PyPI: https://pypi.org/project/<package-name>" ;;
         ruby) echo "- RubyGems: https://rubygems.org/gems/<gem-name>" ;;
         php) echo "- Packagist: https://packagist.org/packages/<vendor>/<package>" ;;
@@ -790,20 +1054,27 @@ if [ -n "$PUBLISH_CMD" ] && [ "$PUBLISH_CMD" != "echo"* ]; then
     echo ""
 fi
 
-if command -v gh >/dev/null && git remote get-url origin | grep -q "github.com"; then
+if command -v gh >/dev/null && git remote get-url origin 2>/dev/null | grep -q "github.com"; then
     REPO_URL=$(git remote get-url origin | sed 's/\.git$//')
     echo "🔗 LINKS:"
     echo "- Release: $REPO_URL/releases/tag/$TAG_NAME"
     echo "- Commits: $REPO_URL/compare/$LAST_TAG...$TAG_NAME"
     echo "- Changelog: $REPO_URL/blob/main/$CHANGELOG_FILE"
+    echo "- Release Notes: $REPO_URL/blob/main/.docs/releases/RELEASE_NOTES_v${NEW_VERSION}.md"
 fi
 
 echo ""
 echo "✅ NEXT STEPS:"
 echo "1. Verify package appears in registry (may take a few minutes)"
 echo "2. Test installation in a fresh environment"
-echo "3. Announce release to users/team"
-echo "4. Update documentation if needed"
+if [ ${#DOC_ISSUES[@]} -gt 0 ]; then
+    echo "3. ⚠️  Address documentation issues (${#DOC_ISSUES[@]} found)"
+    echo "4. Announce release to users/team"
+    echo "5. Review release notes: .docs/releases/RELEASE_NOTES_v${NEW_VERSION}.md"
+else
+    echo "3. Announce release to users/team"
+    echo "4. Review release notes: .docs/releases/RELEASE_NOTES_v${NEW_VERSION}.md"
+fi
 echo ""
 ```
 
@@ -858,5 +1129,9 @@ Before declaring release complete:
 - [ ] Tag created and pushed
 - [ ] Package published (if applicable)
 - [ ] Platform release created (if applicable)
+- [ ] Release notes saved to `.docs/releases/RELEASE_NOTES_v<version>.md`
+- [ ] Documentation alignment verified (ROADMAP, READMEs, docs/)
+- [ ] Version references updated across all documentation
+- [ ] No installation instruction inconsistencies in subpackages
 
 This ensures every release is professional, consistent, and safe across any programming language or ecosystem.

package/src/claude/commands/devflow/code-review.md

@@ -70,24 +70,46 @@ else
     INCLUDE_DB_AUDIT=false
 fi
 echo ""
+
+# Set up audit directory structure
+TIMESTAMP=$(date +%Y-%m-%d_%H%M)
+AUDIT_BASE_DIR=".docs/audits/${CURRENT_BRANCH}"
+mkdir -p "$AUDIT_BASE_DIR"
+
+echo "📁 Audit reports will be saved to: $AUDIT_BASE_DIR"
+echo ""
 ```
 
 ### Step 3: Launch Specialized Sub-Agents in Parallel
 
-Launch these sub-agents in parallel based on change detection:
+Launch these sub-agents in parallel based on change detection.
+
+**IMPORTANT**: Pass the following variables to each sub-agent:
+- `CURRENT_BRANCH`: The branch being reviewed
+- `AUDIT_BASE_DIR`: Base directory for audit reports (`.docs/audits/${CURRENT_BRANCH}`)
+- `TIMESTAMP`: Current timestamp for report filenames
+
+Each sub-agent should save its report to:
+```
+${AUDIT_BASE_DIR}/<audit-type>-report.${TIMESTAMP}.md
+```
+
+**Example paths**:
+- `.docs/audits/feature-auth/security-report.2025-10-18_1430.md`
+- `.docs/audits/feature-auth/performance-report.2025-10-18_1430.md`
 
 **Core Audits (Always Run)**:
-1. audit-security sub-agent
-2. audit-performance sub-agent
-3. audit-architecture sub-agent
-4. audit-tests sub-agent
-5. audit-complexity sub-agent
-6. audit-dependencies sub-agent
-7. audit-documentation sub-agent
+1. audit-security sub-agent → `${AUDIT_BASE_DIR}/security-report.${TIMESTAMP}.md`
+2. audit-performance sub-agent → `${AUDIT_BASE_DIR}/performance-report.${TIMESTAMP}.md`
+3. audit-architecture sub-agent → `${AUDIT_BASE_DIR}/architecture-report.${TIMESTAMP}.md`
+4. audit-tests sub-agent → `${AUDIT_BASE_DIR}/tests-report.${TIMESTAMP}.md`
+5. audit-complexity sub-agent → `${AUDIT_BASE_DIR}/complexity-report.${TIMESTAMP}.md`
+6. audit-dependencies sub-agent → `${AUDIT_BASE_DIR}/dependencies-report.${TIMESTAMP}.md`
+7. audit-documentation sub-agent → `${AUDIT_BASE_DIR}/documentation-report.${TIMESTAMP}.md`
 
 **Conditional Audits** (automatically detect and skip if not applicable):
-8. audit-typescript sub-agent (only if .ts/.tsx files changed or tsconfig.json exists)
-9. audit-database sub-agent (only if database changes detected)
+8. audit-typescript sub-agent → `${AUDIT_BASE_DIR}/typescript-report.${TIMESTAMP}.md`
+9. audit-database sub-agent → `${AUDIT_BASE_DIR}/database-report.${TIMESTAMP}.md`
 
 ### Step 4: Synthesize Comprehensive Review
 
@@ -100,7 +122,13 @@ After all sub-agents complete their analysis:
 
 ### Step 5: Save Comprehensive Review Document
 
-Create a detailed review document at `.docs/reviews/branch-{BRANCH_NAME}-{YYYY-MM-DD_HHMM}.md`:
+Create a detailed review document at `${AUDIT_BASE_DIR}/comprehensive-review.${TIMESTAMP}.md`:
+
+```bash
+REVIEW_FILE="${AUDIT_BASE_DIR}/comprehensive-review.${TIMESTAMP}.md"
+```
+
+**File structure**:
 
 ```markdown
 # Branch Review - {BRANCH_NAME}
@@ -333,7 +361,18 @@ Give the developer a clear, actionable summary:
 - {Easy fix 1} ({estimated time})
 - {Easy fix 2} ({estimated time})
 
-📄 Full review: .docs/reviews/branch-{branch}-{timestamp}.md
+📄 Full review: ${AUDIT_BASE_DIR}/comprehensive-review.${TIMESTAMP}.md
+
+📁 Individual audit reports:
+   ${AUDIT_BASE_DIR}/security-report.${TIMESTAMP}.md
+   ${AUDIT_BASE_DIR}/performance-report.${TIMESTAMP}.md
+   ${AUDIT_BASE_DIR}/architecture-report.${TIMESTAMP}.md
+   ${AUDIT_BASE_DIR}/tests-report.${TIMESTAMP}.md
+   ${AUDIT_BASE_DIR}/complexity-report.${TIMESTAMP}.md
+   ${AUDIT_BASE_DIR}/dependencies-report.${TIMESTAMP}.md
+   ${AUDIT_BASE_DIR}/documentation-report.${TIMESTAMP}.md
+   (+ typescript-report.${TIMESTAMP}.md if applicable)
+   (+ database-report.${TIMESTAMP}.md if applicable)
 
 🔄 NEXT STEPS:
 1. Address blocking issues above

package/src/claude/commands/devflow/debug.md

@@ -1,228 +1,56 @@
 ---
-allowed-tools: Bash, Read, Write, Edit, Grep, Glob, TodoWrite
+allowed-tools: Task
 description: Systematic debugging workflow with issue tracking - use '/debug [issue description]'
 ---
 
 ## Your task
 
-Guide a systematic debugging session for the issue: `$ARGUMENTS`
+Launch the `debug` sub-agent to conduct systematic debugging for: `$ARGUMENTS`
 
-If no arguments provided, prompt for issue description. Otherwise, use the provided description as the problem to debug.
+If no arguments provided, prompt the user for the issue description.
 
-### Step 1: Capture the Problem
+### Debugging Process
 
-```bash
-# Create debug session tracking
-DEBUG_SESSION="debug-$(date +%Y%m%d-%H%M%S)"
-mkdir -p .docs/debug
+The debug agent will:
 
-# Use provided arguments or default
-ISSUE_DESC="${ARGUMENTS:-No issue description provided}"
+1. **Capture the Problem** - Create debug session tracking with unique session ID
+2. **Document the Issue** - Create comprehensive debug log in `.docs/debug/`
+3. **Smart Investigation** - Detect issue type (error/performance/test/build) and adapt strategy
+4. **Generate Hypotheses** - Create targeted, testable hypotheses based on issue type
+5. **Systematic Testing** - Test each hypothesis methodically and document findings
+6. **Root Cause Analysis** - Identify precise root cause with file and line references
+7. **Implement Fix** - Design, implement, and verify the solution
+8. **Prevention Strategy** - Document how to prevent similar issues
+9. **Update Knowledge Base** - Add to searchable `.docs/debug/KNOWLEDGE_BASE.md`
 
-echo "=== DEBUG SESSION STARTED ==="
-echo "Session ID: $DEBUG_SESSION"
-echo "Issue: $ISSUE_DESC"
-echo "Branch: $(git branch --show-current)"
-echo "Time: $(date)"
-echo ""
-```
-
-### Step 2: Document the Issue
+### Next: Synthesize Results
 
-Create debug log at `.docs/debug/{DEBUG_SESSION}.md`:
+After the sub-agent completes, present a concise summary to the user:
 
 ```markdown
-# Debug Session - {DEBUG_SESSION}
-
-## Problem Statement
-**Issue**: $ARGUMENTS
-**Reported**: {timestamp}
-**Branch**: {current_branch}
-
-## Expected vs Actual Behavior
-**Expected**: {What should happen - analyze from issue description}
-**Actual**: {What's happening instead}
-
-## Error Details
-```
-{If error message in $ARGUMENTS, extract and display}
-```
-
-## Initial Assessment
-{Quick analysis of the issue based on the description}
-```
+🔍 DEBUG SESSION COMPLETE: $ARGUMENTS
 
-### Step 3: Smart Investigation Based on Issue Type
-
-Analyze `$ARGUMENTS` to determine investigation strategy:
-
-```bash
-# Parse issue type from arguments
-ISSUE_LOWER=$(echo "$ARGUMENTS" | tr '[:upper:]' '[:lower:]')
-
-# Determine investigation type
-if echo "$ISSUE_LOWER" | grep -q "error\|exception\|crash\|fail"; then
-    echo "🔍 ERROR INVESTIGATION MODE"
-    # Search for error patterns in logs
-    find . -name "*.log" -type f -exec grep -l "ERROR\|EXCEPTION\|FAIL" {} \; 2>/dev/null | head -5
-
-    # Check recent error outputs
-    grep -r "ERROR\|Exception\|Failed" --include="*.log" --include="*.txt" . 2>/dev/null | tail -10
-
-elif echo "$ISSUE_LOWER" | grep -q "slow\|performance\|timeout\|lag"; then
-    echo "⚡ PERFORMANCE INVESTIGATION MODE"
-    # Look for performance bottlenecks
-    echo "Checking for large files that might cause issues:"
-    find . -type f -size +10M 2>/dev/null | head -5
-
-    echo "Recent changes to critical paths:"
-    git diff HEAD~5 --name-only | grep -E "\.(js|ts|py|go|rs)$" | head -10
-
-elif echo "$ISSUE_LOWER" | grep -q "test\|spec\|unit\|integration"; then
-    echo "🧪 TEST FAILURE INVESTIGATION MODE"
-    # Focus on test files and recent test changes
-    echo "Recent test file changes:"
-    git diff HEAD~5 --name-only | grep -E "(test|spec)\." | head -10
-
-    # Run tests if possible
-    npm test 2>&1 | tail -20 || echo "Test command not available"
-
-elif echo "$ISSUE_LOWER" | grep -q "build\|compile\|webpack\|bundle"; then
-    echo "🔨 BUILD ISSUE INVESTIGATION MODE"
-    # Check build configurations and recent changes
-    echo "Build configuration files:"
-    ls -la | grep -E "(webpack|rollup|vite|tsconfig|babel|eslint)"
-
-    echo "Recent config changes:"
-    git diff HEAD~5 --name-only | grep -E "\.(json|config\.|rc)" | head -10
-
-else
-    echo "🔍 GENERAL INVESTIGATION MODE"
-    # General investigation for unspecified issues
-    echo "Recent changes that might be related:"
-    git log --oneline -10
-    echo ""
-    echo "Modified files (uncommitted):"
-    git status --short
-fi
-```
-
-### Step 4: Generate Targeted Hypotheses
+## 🎯 ROOT CAUSE
+{Precise description with file:line}
 
-Based on the issue type detected, use TodoWrite to create specific debugging tasks:
+## ✅ SOLUTION APPLIED
+{Description of fix}
 
-```markdown
-## Debugging Tasks for: $ARGUMENTS
+## 📝 VERIFICATION
+{Test results showing fix works}
 
-Based on the issue description, here are targeted hypotheses to investigate:
-
-- [ ] Check if issue is reproducible consistently
-- [ ] Verify issue occurs in clean environment
-- [ ] {Specific hypothesis based on issue type}
-- [ ] {Another specific hypothesis}
-- [ ] Review recent changes in related files
-```
-
-### Step 5: Interactive Debugging Process
-
-Guide through systematic testing of each hypothesis:
-
-```bash
-echo "=== HYPOTHESIS TESTING ==="
-echo "Testing each hypothesis systematically..."
-
-# For each hypothesis, provide specific commands and checks
-# based on the issue type identified from $ARGUMENTS
-```
-
-### Step 6: Track Solution
-
-Once issue is identified and fixed:
-
-```markdown
-## Solution Found
-
-### Root Cause
-{Identified from investigation}
-
-### Fix Applied
-```{language}
-{Code changes made}
-```
-
-### Verification
-- [ ] Issue no longer reproduces with: $ARGUMENTS
-- [ ] Related tests pass
-- [ ] No new issues introduced
-
-### Prevention
+## 🛡️ PREVENTION
 {How to prevent similar issues}
 
-### Time Analysis
-- Detection to Fix: {time}
-- Debugging approach: {what worked}
-```
-
-### Step 7: Create Fix Commit
-
-```bash
-# If files were modified during debugging
-if [ -n "$(git status --porcelain)" ]; then
-    echo "=== CREATING FIX COMMIT ==="
-    echo "Files modified during debugging:"
-    git status --short
-
-    # Suggested commit message based on the issue
-    echo ""
-    echo "Suggested commit message:"
-    echo "fix: $ARGUMENTS"
-    echo ""
-    echo "Debug session: $DEBUG_SESSION"
-    echo "Root cause: {identified cause}"
-    echo "Solution: {applied fix}"
-fi
-```
-
-### Step 8: Learning Documentation
-
-Append to `.docs/debug/KNOWLEDGE_BASE.md`:
-
-```markdown
-## Issue: $ARGUMENTS
-**Date**: {date}
-**Category**: {error/performance/test/build/other}
-**Solution**: {brief solution}
-**Key Learning**: {what to remember}
-**Keywords**: {searchable terms}
----
-```
-
-This creates a searchable knowledge base of debugging sessions for future reference.
-
-### Final Output
-
-```markdown
-## 🔍 Debug Session Complete
-
-**Issue**: $ARGUMENTS
-**Session**: $DEBUG_SESSION
-**Status**: {Resolved/Partially Resolved/Needs More Investigation}
-
-### Summary
-{Brief summary of what was found and fixed}
-
-### Files Changed
-{List of modified files if any}
-
-### Next Steps
-{Any follow-up actions needed}
+## 📄 DOCUMENTATION
+- Debug log: `.docs/debug/{SESSION_ID}.md`
+- Knowledge base: `.docs/debug/KNOWLEDGE_BASE.md`
 
-📄 Full debug log: .docs/debug/$DEBUG_SESSION.md
-📚 Knowledge base updated: .docs/debug/KNOWLEDGE_BASE.md
+📄 Full debugging details available from sub-agent output above
 ```
 
 💡 **Usage Examples**:
 - `/debug "TypeError: Cannot read property 'name' of undefined"`
 - `/debug tests failing after npm update`
 - `/debug app crashes on startup`
-- `/debug slow performance in search feature`
+- `/debug slow performance in search feature`