Bugs

/bugs (v2.37)

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

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

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 /Users/alfredolopez/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

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

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 ~/.ralph/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

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