alfredolopez80/bugs

/bugs (v2.37)

Deep bug analysis using Codex gpt-5.2-codex with the bug-hunter skill and TLDR context optimization.

v2.88 Key Changes (MODEL-AGNOSTIC)

• Model-agnostic: Uses model configured in ~/.claude/settings.json or CLI/env vars
• No flags required: Works with the configured default model
• Flexible: Works with GLM-5, Claude, Minimax, or any configured model
• Settings-driven: Model selection via ANTHROPIC_DEFAULT_*_MODEL env vars

Agent Teams Integration (v2.88)

Optimal Scenario: Pure Custom Subagents

This skill uses Pure Custom Subagents (no Agent Teams) for specialized, focused bug analysis.

Why Scenario B for Bug Hunting

• Specialized task: Bug analysis is a focused, single-purpose operation
• Less coordination needed: Direct spawn faster than team creation for single-file analysis
• Tool restrictions important: ralph-reviewer restricted to Read/Grep/Glob prevents accidental modifications
• Scalable pattern: For large codebases, spawn multiple reviewers directly without team overhead

Configuration

1. No TeamCreate: Skip team creation overhead for faster execution
2. Direct Task: Spawn ralph-reviewer agents directly with analysis prompts
3. Tool Restrictions: Leverage per-agent tool limits (Read/Grep/Glob only for reviewers)
4. Model Inheritance: Use model configured in settings.json

Workflow Pattern

Task(subagent_type="ralph-reviewer", prompt="Analyze $TARGET for bugs...")
  → Agent executes with restricted tools (no Write/Edit)
  → Returns structured bug findings
  → Complete (no team cleanup needed)

For Large Codebases (Parallel Scanning)

When analyzing directories with many files:

# Spawn multiple reviewers in parallel (no team needed)
Task(subagent_type="ralph-reviewer", prompt="Analyze files 1-10...")
Task(subagent_type="ralph-reviewer", prompt="Analyze files 11-20...")
Task(subagent_type="ralph-reviewer", prompt="Analyze files 21-30...")

# Aggregate results manually or via simple script

When NOT to Use Agent Teams

• Single-file bug analysis (most common case)
• Quick scans without multi-phase coordination
• When tool restrictions (no Write/Edit) are more important than coordination
• When team creation overhead exceeds analysis time

Pre-Bugs: TLDR Context Preparation (v2.37)

AUTOMATIC - Before bug hunting, gather context with 95% token savings:

# Get function signatures and call flow
tldr context "$TARGET_FILE" . > /tmp/bugs-context.md

# Get dependency graph for tracking bug propagation
tldr deps "$TARGET_FILE" . > /tmp/bugs-deps.md

# Get codebase structure for understanding module relationships
tldr structure . > /tmp/bugs-structure.md

# Semantic search for error handling patterns
tldr semantic "try catch error exception throw" .

Overview

The /bugs command performs comprehensive static analysis using TLDR-compressed context to identify potential bugs, logic errors, race conditions, edge cases, and other code issues that could cause runtime failures or unexpected behavior. It uses Codex GPT-5.2 model with specialized bug-hunting capabilities to analyze code paths, detect anti-patterns, and suggest fixes.

Unlike traditional linters, Codex bug hunting performs deep semantic analysis:

• Context-aware: Understands code intent and business logic
• Multi-file analysis: Traces bugs across module boundaries
• Pattern recognition: Identifies common bug patterns and anti-patterns
• Fix suggestions: Provides actionable remediation steps

When to Use

Use /bugs when:

• Investigating mysterious test failures or production issues
• Auditing newly merged code for potential issues
• Debugging complex interactions between modules
• Preparing critical code paths for production deployment
• Reviewing legacy code for modernization
• Searching for edge cases before stress testing
• Performing pre-merge quality checks (complexity >= 7)

Analysis Methodology

Codex bug hunting follows a systematic approach:

1. Static Analysis: Parse AST and control flow graphs
2. Pattern Matching: Compare against known bug patterns database
3. Semantic Understanding: Analyze code intent and data flow
4. Edge Case Detection: Identify boundary conditions and error paths
5. Severity Assessment: Classify bugs by impact and probability
6. Fix Generation: Propose concrete remediation steps

Bug Categories

| Category | Examples | Severity | |----------|----------|----------| | Logic Errors | Off-by-one, incorrect conditions, wrong operators | HIGH | | Race Conditions | Unprotected shared state, TOCTOU bugs | HIGH | | Memory Issues | Leaks, use-after-free, buffer overflows | CRITICAL | | Type Errors | Implicit conversions, type coercion bugs | MEDIUM | | Error Handling | Uncaught exceptions, missing null checks | HIGH | | Edge Cases | Empty arrays, boundary values, overflow | MEDIUM | | Async Issues | Unhandled promises, callback hell, deadlocks | HIGH | | Security Bugs | Injection, XSS, CSRF (see /security for full audit) | CRITICAL |

CLI Execution

# Bug hunt on specific file
ralph bugs src/auth/login.ts

# Bug hunt on directory
ralph bugs src/components/

# Bug hunt on entire codebase
ralph bugs .

# Background execution with logging
ralph bugs src/ > bugs-report.json 2>&1 &

Task Tool Invocation (TLDR-Enhanced)

Use the Task tool to invoke Codex bug hunting with TLDR context:

Task:
  subagent_type: "debugger"
  model: "sonnet"
  run_in_background: true
  description: "Codex bug hunting analysis"
  prompt: |
    # Context (95% token savings via tldr)
    Structure: $(tldr structure .)
    File Context: $(tldr context $ARGUMENTS .)
    Dependencies: $(tldr deps $ARGUMENTS .)

    Execute Codex bug hunting via CLI:
    cd ~/Documents/GitHub/multi-agent-ralph-loop && \
    codex exec --yolo --enable-skills -m gpt-5.2-codex \
    "Use bug-hunter skill. Find bugs in: $ARGUMENTS

    Output JSON: {
      bugs: [
        {
          severity: 'CRITICAL|HIGH|MEDIUM|LOW',
          type: 'logic|race|memory|type|error-handling|edge-case|async|security',
          file: 'path/to/file.ts',
          line: 42,
          description: 'Clear bug description',
          fix: 'Concrete remediation steps'
        }
      ],
      summary: {
        total: 5,
        high: 2,
        medium: 2,
        low: 1,
        approved: false
      }
    }"

    Apply Ralph Loop: iterate until all HIGH+ bugs are resolved or approved.

Direct Codex Execution

For immediate results without Task orchestration:

codex exec --yolo --enable-skills -m gpt-5.2-codex \
  "Use bug-hunter skill. Find bugs in: src/

  Focus on:
  - Race conditions in async code
  - Uncaught promise rejections
  - Type coercion issues
  - Edge case handling

  Output JSON with severity, type, file, line, description, fix"

Output Format

The bug hunting analysis returns structured JSON:

{
  "bugs": [
    {
      "severity": "HIGH",
      "type": "race",
      "file": "src/auth/session.ts",
      "line": 87,
      "description": "Race condition: session.user accessed before async initialization completes",
      "fix": "Add await before accessing session.user, or use Promise.all() to ensure initialization"
    },
    {
      "severity": "MEDIUM",
      "type": "edge-case",
      "file": "src/utils/parser.ts",
      "line": 23,
      "description": "Empty array not handled: arr[0] will throw if arr is empty",
      "fix": "Add guard: if (arr.length === 0) return null; before accessing arr[0]"
    }
  ],
  "summary": {
    "total": 2,
    "high": 1,
    "medium": 1,
    "low": 0,
    "approved": false
  }
}

Severity Levels

| Severity | Meaning | Action | |----------|---------|--------| | CRITICAL | Production-breaking, security issues | MUST FIX before merge | | HIGH | Likely to cause failures, data corruption | SHOULD FIX before merge | | MEDIUM | Edge cases, potential issues under load | Review and decide | | LOW | Code smells, minor improvements | Optional fix |

Integration

The /bugs command integrates with other Ralph workflows:

With @debugger Agent

Task:
  subagent_type: "debugger"
  model: "opus"  # Opus for deep analysis
  description: "Full debugging workflow"
  prompt: |
    1. Run /bugs on $TARGET
    2. Analyze top 5 HIGH severity bugs
    3. Trace execution paths to root cause
    4. Propose fixes with test cases
    5. Validate fixes pass quality gates

With /adversarial

When a bug fix needs a clarified spec:

# Step 1: Bug hunting
ralph bugs src/payment/

# Step 2: Draft a short spec for the fix
ralph adversarial "Draft: Fix payment retry logic with idempotency"

With /unit-tests

Generate tests that specifically target discovered bugs:

Task:
  subagent_type: "test-architect"
  model: "sonnet"
  prompt: |
    Read bugs-report.json
    For each HIGH/CRITICAL bug:
    - Write failing test that reproduces bug
    - Verify test fails before fix
    - Apply fix from bug report
    - Verify test passes after fix

    Use TDD pattern: RED → FIX → GREEN

Related Commands

| Command | Purpose | When to Use | |---------|---------|-------------| | /security | Security-focused audit (CWE checks) | Before production deploy | | /unit-tests | Generate test coverage | After bug fixes | | /refactor | Improve code structure | After identifying patterns | | /adversarial | Adversarial spec refinement | Critical code paths | | /full-review | Comprehensive analysis (6 agents) | Major features/releases |

Ralph Loop Integration

The /bugs command follows the Ralph Loop pattern with these hooks:

┌─────────────────────────────────────────────────────────┐
│ RALPH LOOP: Bug Hunting                                 │
├─────────────────────────────────────────────────────────┤
│                                                         │
│ 1. EXECUTE   → codex exec bug-hunter                    │
│ 2. VALIDATE  → Check severity counts                    │
│ 3. ITERATE   → Fix HIGH+ bugs                           │
│ 4. VERIFY    → Re-run until summary.approved = true     │
│                                                         │
│ Quality Gate: No HIGH+ bugs OR all explicitly approved  │
│ Max Iterations: 15 (Codex GPT-5.2)                      │
│                                                         │
└─────────────────────────────────────────────────────────┘

Approval Criteria

The bug hunting loop continues until:

• Zero HIGH+ bugs detected, OR
• All HIGH+ bugs explicitly approved by user with justification
• Quality gates pass (no new bugs introduced by fixes)

Example Workflow

Full bug hunting and remediation workflow:

# 1. Initial bug scan
ralph bugs src/

# 2. Review report
cat .claude/tmp/codex_bugs.json | jq '.summary'

# 3. Fix HIGH severity bugs
# (manual or via /refactor)

# 4. Verify fixes
ralph bugs src/  # Should show reduced bug count

# 5. Generate regression tests
ralph unit-tests src/

# 6. Run quality gates
ralph gates

# 7. Final approval (if LOW bugs remain)
# Add to bugs-report.json: "approved": true, "justification": "Low risk edge cases"

Best Practices

1. Run before merge: Always scan critical paths before PR approval
2. Prioritize HIGH+: Focus on CRITICAL and HIGH severity first
3. Fix root causes: Don't just patch symptoms
4. Add tests: Every fixed bug needs a regression test
5. Track patterns: If same bug type appears multiple times, refactor pattern
6. Combine with /security: Bug hunting finds logic errors, security finds vulnerabilities
7. Use Opus for critical: Switch to --model opus for payment/auth/crypto code

Cost Optimization

| Model | Cost | Speed | When to Use | |-------|------|-------|-------------| | GPT-5.2-Codex | ~15% | Fast | Default for bug hunting | | Opus | 100% | Slow | Critical code paths | | Sonnet | 60% | Medium | Task orchestration only |

Recommended: Codex GPT-5.2 for bug hunting (optimized for code analysis)

Action Reporting (v2.93.0)

Esta skill genera reportes automáticos completos para trazabilidad:

Reporte Automático

Cuando esta skill completa, se genera automáticamente:

1. En la conversación de Claude: Resultados visibles
2. En el repositorio: docs/actions/bugs/{timestamp}.md
3. Metadatos JSON: .claude/metadata/actions/bugs/{timestamp}.json

Contenido del Reporte

Cada reporte incluye:

• ✅ Summary: Descripción de la tarea ejecutada
• ✅ Execution Details: Duración, iteraciones, archivos modificados
• ✅ Results: Errores encontrados, recomendaciones
• ✅ Next Steps: Próximas acciones sugeridas

Ver Reportes Anteriores

# Listar todos los reportes de esta skill
ls -lt docs/actions/bugs/

# Ver el reporte más reciente
cat $(ls -t docs/actions/bugs/*.md | head -1)

# Buscar reportes fallidos
grep -l "Status: FAILED" docs/actions/bugs/*.md

Generación Manual (Opcional)

source .claude/lib/action-report-lib.sh
start_action_report "bugs" "Task description"
# ... ejecución ...
complete_action_report "success" "Summary" "Recommendations"

Referencias del Sistema

• Action Reports System - Documentación completa
• action-report-lib.sh - Librería helper
• action-report-generator.sh - Generador