sea-debug

name	sea-debug
description	Debug SEA-Forge specific issues including code generation failures, spec validation errors, handler mismatches, and runtime problems.

SEA Debugging

Debug SEA-Forge specific issues across the pipeline: code generation, spec validation, handler mismatches, runtime errors, and integration problems.

When to Use

Invoke when:

• Code generation fails
• Spec validation errors
• Handlers don't match spec
• Runtime errors in generated code
• Integration failures
• Pipeline breaks

Usage

User invokes with:

• "Debug the generation failure"
• "Why is spec validation failing?"
• "Handlers not working after regeneration"
• "Pipeline failed, investigate"

Debug Process

Step 1: Identify Issue Category

echo "🔍 Identifying issue category..."

# Check spec files
if find docs/specs -name "*.yaml" -exec calm validate {} \; 2>&1 | grep -q error; then
  CATEGORY="spec_validation"
elif ! just pipeline 2>&1 | grep -q "Generation successful"; then
  CATEGORY="code_generation"
elif ! pnpm test 2>&1 | grep -q "passing"; then
  CATEGORY="test_failure"
else
  CATEGORY="runtime_error"
fi

echo "Issue category: $CATEGORY"

Step 2: Collect Diagnostic Information

# SEA-Forg diagnostics
echo "--- SEA Environment ---"
just env || echo "just env not available"

echo "--- Nx Workspace ---"
pnpm exec nx report

echo "--- Spec Validation ---"
find docs/specs -name "*.yaml" -exec calm validate {} \; 2>&1 | head -20

echo "--- Generated Code Status ---"
find . -path "*/src/gen/*" -type f | head -20

echo "--- Recent Pipeline Runs ---"
git log --oneline -10 --grep="pipeline\|generate"

echo "--- Test Status ---"
pnpm test --reporter=verbose 2>&1 | tail -50

Step 3: Analyze Common Issues

Issue: Spec Validation Failures

echo "🔍 Analyzing spec validation..."

# Check for syntax errors
for spec in docs/specs/**/*.yaml; do
  if ! yq eval '.' "$spec" > /dev/null 2>&1; then
    echo "❌ YAML syntax error: $spec"
    yq eval '.' "$spec" 2>&1 | head -10
  fi
done

# Check for missing required fields
for spec in docs/specs/**/*.yaml; do
  echo "--- Checking: $spec ---"
  yq eval '
    .context as $context |
    .domain as $domain |
    .api_surface as $api |
    if $context == null then error("Missing context section") end |
    if $domain == null then error("Missing domain section") end |
    if $api == null then error("Missing api_surface section") end
  ' "$spec" 2>&1 || true
done

# Check CALM compliance
if command -v calm &> /dev/null; then
  echo "--- CALM Validation ---"
  calm validate docs/specs/ 2>&1 | head -30
fi

Issue: Code Generation Failures

echo "🔍 Analyzing code generation..."

# Run pipeline with verbose output
just pipeline --verbose 2>&1 | tee tmp/pipeline-debug.log

# Check for common errors
echo "--- Common Generation Errors ---"
grep -i "error\|fail\|exception" tmp/pipeline-debug.log | head -20

# Check spec-to-handler mapping
echo "--- Spec to Handler Mapping ---"
for spec in docs/specs/**/*spec.yaml; do
  CONTEXT=$(yq e '.context.name' "$spec")
  echo "Context: $CONTEXT"
  echo "Spec: $spec"
  echo "Handlers:"
  find "apps/$CONTEXT/src/gen" -name "*.ts" 2>/dev/null | head -5 || echo "  No handlers found"
  echo ""
done

Issue: Handler Mismatches

echo "🔍 Analyzing handler mismatches..."

# Compare spec endpoints to generated handlers
for spec in docs/specs/**/*spec.yaml; do
  CONTEXT=$(yq e '.context.name' "$spec")

  # Get expected endpoints from spec
  EXPECTED=$(yq e '.api_surface.endpoints[].name' "$spec" | sort)

  # Get actual handlers
  ACTUAL=$(find "apps/$CONTEXT/src/gen" -name "*Handler.ts" -exec basename {} \; | sed 's/Handler.ts//' | sort)

  # Compare
  echo "--- Context: $CONTEXT ---"
  echo "Expected endpoints:"
  echo "$EXPECTED" | while read ep; do
    if echo "$ACTUAL" | grep -q "^$ep$"; then
      echo "  ✅ $ep"
    else
      echo "  ❌ $ep (missing)"
    fi
  done

  echo "Extra handlers:"
  echo "$ACTUAL" | while read handler; do
    if ! echo "$EXPECTED" | grep -q "^$handler$"; then
      echo "  ⚠️  $handler (not in spec)"
    fi
  done
done

Issue: Runtime Errors

echo "🔍 Analyzing runtime errors..."

# Check recent error logs
echo "--- Recent Error Logs ---"
if [ -f "logs/error.log" ]; then
  tail -50 logs/error.log
fi

# Check for common patterns
echo "--- Common Error Patterns ---"

# Missing environment variables
grep -r "process.env\." src/ | grep -v "test" | while read line; do
  VAR=$(echo "$line" | grep -oE 'process\.env\.[A-Z_]+' | sort -u)
  if [ -n "$VAR" ]; then
    echo "Check if $VAR is set"
  fi
done

# Missing dependencies
echo "--- Checking for missing imports ---"
find src -name "*.ts" -exec grep -h "^import" {} \; | sort -u > tmp/imports.txt
while read dep; do
  if ! grep -q "$dep" package.json; then
    echo "⚠️  Possibly missing: $dep"
  fi
done < tmp/imports.txt

Step 4: Generate Fix Recommendations

echo "💡 Generating fix recommendations..."

# Based on issue category
case "$CATEGORY" in
  spec_validation)
    echo "Spec Validation Fixes:"
    echo "1. Fix YAML syntax errors"
    echo "2. Add missing required fields"
    echo "3. Run calm validate docs/specs/"
    echo "4. Check CALM compliance"
    ;;

  code_generation)
    echo "Code Generation Fixes:"
    echo "1. Check spec validity: calm validate docs/specs/"
    echo "2. Clear generation cache: rm -rf src/gen/"
    echo "3. Regenerate: just pipeline <context>"
    echo "4. Check handler-generator logs"
    ;;

  handler_mismatch)
    echo "Handler Mismatch Fixes:"
    echo "1. Update spec with missing endpoints"
    echo "2. Regenerate handlers: just pipeline <context>"
    echo "3. Remove orphaned handlers"
    echo "4. Validate spec: /spec-validate"
    ;;

  runtime_error)
    echo "Runtime Error Fixes:"
    echo "1. Check environment variables"
    echo "2. Verify dependencies: pnpm install"
    echo "3. Check logs: tail -f logs/error.log"
    echo "4. Run tests: pnpm test"
    ;;
esac

Step 5: Create Debug Report

cat > tmp/debug-report.md <<EOF
# SEA Debug Report

**Date**: $(date -u +%Y-%m-%dT%H:%M:%SZ)
**Category**: $CATEGORY
**Branch**: $(git branch --show-current)
**Commit**: $(git log -1 --format=%h)

## Issue Description
{user's issue description}

## Diagnostic Information

### Environment
\`\`\`
$(just env 2>&1 || echo "Not available")
\`\`\`

### Validation Status
- Spec validation: {$SPEC_STATUS}
- Code generation: {$GEN_STATUS}
- Tests: {$TEST_STATUS}

## Findings
{analysis findings}

## Recommendations
{fix recommendations}

## Next Steps
1. {step 1}
2. {step 2}
3. {step 3}
EOF

echo "Debug report: tmp/debug-report.md"

Common Issues and Fixes

"Generated code has errors"

Cause: Spec changed but handlers not regenerated

Fix:

# Clear and regenerate
rm -rf apps/*/src/gen/*
just pipeline

# Or regenerate specific context
just pipeline user-management

"Spec validation fails"

Cause: Invalid YAML or missing fields

Fix:

# Validate specific spec
calm validate docs/specs/my-spec.yaml

# Check syntax
yq eval '.' docs/specs/my-spec.yaml

# Fix reported issues

"Handler not found"

Cause: Spec and handlers out of sync

Fix:

# Compare spec to handlers
# See "Handler Mismatches" above

# Regenerate from spec
just pipeline <context>

"Tests fail after generation"

Cause: Generated handlers need domain implementation

Fix:

# Implement domain layer
# Update src/domain/*.ts files

# Or update tests to match new signatures

Debug Commands Quick Reference

# Validate all specs
calm validate docs/specs/

# Generate handlers
just pipeline

# Run tests
pnpm test

# Check environment
just env

# View logs
tail -f logs/error.log

# Nx graph
pnpm exec nx graph

# Nx affected
pnpm exec nx affected

Integration

• Integrates with debugging-codegen-pipeline for pipeline issues
• Integrates with observability-debugging for runtime issues
• Integrates with governance-validation for spec issues
• Integrates with nx-workspace for workspace issues

Output

After debugging:

## Debug Analysis Complete

**Issue Category**: {category}
**Root Cause**: {cause}
**Severity**: {critical|high|medium|low}

### Findings
{detailed findings}

### Recommended Fixes
1. {fix 1}
2. {fix 2}
3. {fix 3}

### Commands to Run
\`\`\`bash
{commands}
\`\`\`

### Prevention
{how to prevent this issue}

### Debug Report
Full report: tmp/debug-report.md