Claude-Code-Workflow/.claude/commands/cli/mode/bug-index.md

name, description, argument-hint, allowed-tools

name	description	argument-hint	allowed-tools
bug-index	Bug analysis and fix suggestions using CLI tools	[--agent] [--tool codex|gemini|qwen] [--enhance] [--cd path] bug description	SlashCommand(*), Bash(*), Task(*)

CLI Mode: Bug Index (/cli:mode:bug-index)

Purpose

Systematic bug analysis with diagnostic template (~/.claude/prompt-templates/bug-fix.md).

Supported Tools: codex, gemini (default), qwen Key Feature: --cd flag for directory-scoped analysis

Parameters

• --agent - Use cli-execution-agent for automated context discovery (5-phase intelligent mode)
• --tool <codex|gemini|qwen> - Tool selection (default: gemini, ignored in agent mode)
• --enhance - Enhance bug description with /enhance-prompt first
• --cd "path" - Target directory for focused analysis
• <bug-description> (Required) - Bug description or error message

Execution Flow

Standard Mode (Default)

1. Parse tool selection: Extract --tool flag (default: gemini)
2. If --enhance flag present: Execute /enhance-prompt "[bug-description]" first
3. Parse bug description (original or enhanced)
4. Detect target directory (from --cd or auto-infer)
5. Build command for selected tool with bug-fix template
6. Execute analysis (read-only, provides fix recommendations)
7. Save to .workflow/WFS-[id]/.chat/bug-index-[timestamp].md

Agent Mode (--agent flag)

Delegate bug analysis to cli-execution-agent for intelligent debugging with automated context discovery.

Agent invocation:

Task(
  subagent_type="cli-execution-agent",
  description="Analyze bug with automated context discovery",
  prompt=`
    Task: ${bug_description}
    Mode: debug (bug analysis)
    Tool Preference: ${tool_flag || 'auto-select'}
    ${cd_flag ? `Directory Scope: ${cd_path}` : ''}
    Template: bug-fix

    Agent will autonomously:
    - Discover bug-related files and error traces
    - Build debug prompt with bug-fix template
    - Execute analysis and provide fix recommendations
    - Save analysis log
  `
)

The agent handles all phases internally.

Core Rules

1. Analysis Only: This command analyzes bugs and suggests fixes - it does NOT modify code
2. Enhance First (if flagged): Execute /enhance-prompt before analysis
3. Directory Context: Use cd when --cd provided or auto-detected
4. Template Required: Always use bug-fix template
5. Session Output: Save analysis results and fix recommendations to session chat

Analysis Focus (via Template)

• Root cause investigation and diagnosis
• Code path tracing to locate issues
• Targeted minimal fix recommendations
• Impact assessment of proposed changes

Command Template

cd [directory] && gemini -p "
PURPOSE: [bug analysis goal]
TASK: Systematic bug analysis and fix recommendations
MODE: analysis
CONTEXT: @CLAUDE.md @**/*CLAUDE.md [entire codebase in directory]
EXPECTED: Root cause analysis, code path tracing, targeted fix suggestions
RULES: $(cat ~/.claude/prompt-templates/bug-fix.md) | Bug: [description]
"

Examples

Basic Bug Analysis (Standard Mode):

/cli:mode:bug-index "null pointer error in login flow"
# Executes: Gemini with bug-fix template
# Returns: Root cause analysis, fix recommendations

Intelligent Bug Analysis (Agent Mode):

/cli:mode:bug-index --agent "intermittent token validation failure"
# Phase 1: Classifies as debug task, extracts keywords ['token', 'validation', 'failure']
# Phase 2: MCP discovers token validation code, middleware, test files with errors
# Phase 3: Builds debug prompt with bug-fix template + discovered error patterns
# Phase 4: Executes Gemini with comprehensive bug context
# Phase 5: Saves analysis log with detailed fix recommendations
# Returns: Root cause analysis + code path traces + minimal fix suggestions

Standard Template Example:

cd . && gemini -p "
PURPOSE: Debug authentication null pointer error
TASK: Identify root cause and provide fix recommendations
MODE: analysis
CONTEXT: @CLAUDE.md @**/*CLAUDE.md
EXPECTED: Root cause, code path, minimal fix suggestion, impact assessment
RULES: $(cat ~/.claude/prompt-templates/bug-fix.md) | Bug: null pointer in login flow
"

Directory-Specific:

cd src/auth && gemini -p "
PURPOSE: Fix token validation failure
TASK: Analyze token validation bug in auth module
MODE: analysis
CONTEXT: @CLAUDE.md @**/*CLAUDE.md
EXPECTED: Validation logic analysis, fix recommendation with minimal changes
RULES: $(cat ~/.claude/prompt-templates/bug-fix.md) | Bug: token validation fails intermittently
"

Bug Investigation Workflow

# 1. Find bug-related files
rg "error_keyword" --files-with-matches
mcp__code-index__search_code_advanced(pattern="error|exception", file_pattern="*.ts")

# 2. Execute bug analysis with focused context (analysis only, no code changes)
/cli:mode:bug-index --cd "src/module" "specific error description"

Output Routing

Output Destination Logic:

• Active session exists AND bug is session-relevant:
  • Save to .workflow/WFS-[id]/.chat/bug-index-[timestamp].md
• No active session OR quick debugging:
  • Save to .workflow/.scratchpad/bug-index-[description]-[timestamp].md

Examples:

• During active session WFS-payment-fix, analyzing payment bug → .chat/bug-index-20250105-143022.md
• No session, quick null pointer investigation → .scratchpad/bug-index-null-pointer-20250105-143045.md

Notes

• Command templates and file patterns: see intelligent-tools-strategy.md (loaded in memory)
• Scratchpad directory details: see workflow-architecture.md
• Template path: ~/.claude/prompt-templates/bug-fix.md
• Uses @**/* for in CONTEXT field for comprehensive codebase context