--- name: debug-cli description: Use when users need to debug, modify, or extend the code-forge application's CLI commands, argument parsing, or CLI behavior. This includes adding new commands, fixing CLI bugs, updating command options, or troubleshooting CLI-related issues. --- # CLI Debug Skill This skill provides a systematic workflow for debugging and verifying changes to the forge CLI application. ## Core Principles 1. **Always get latest docs first**: Run `--help` to see current commands and options 2. **Use `-p` for testing**: Test forge by giving it tasks with the `-p` flag 3. **Never commit**: This is for debugging only - don't commit changes 4. **Clone conversations**: When debugging conversation bugs, clone the source conversation before reproducing ## Workflow ### 1. Build the Application Always build in debug mode after making changes: ```bash cargo build ``` **Never** use `cargo build --release` for debugging - it's significantly slower and unnecessary for verification. ### 2. Get Latest Documentation **Always** start by checking the latest help to understand current commands and options: ```bash # Main help - do this first ./target/debug/forge --help # Command-specific help ./target/debug/forge [COMMAND] --help # Subcommand help ./target/debug/forge [COMMAND] [SUBCOMMAND] --help ``` ### 3. Test with `-p` Flag Use the `-p` flag to give forge a task to complete without interactive mode: ```bash # Test with a simple prompt ./target/debug/forge -p "create a hello world rust program" # Test with specific functionality ./target/debug/forge -p "read the README.md file and summarize it" # Test with complex tasks ./target/debug/forge -p "analyze the code structure and suggest improvements" ``` ### 4. Debug with Conversation Dumps When debugging prompts or conversation issues, use `conversation dump` to export conversations. The command automatically creates a timestamped file: ```bash # Dump conversation as JSON (creates: YYYY-MM-DD_HH-MM-SS-dump.json) ./target/debug/forge conversation dump # Export as HTML for human-readable format (creates: YYYY-MM-DD_HH-MM-SS-dump.html) ./target/debug/forge conversation dump --html # Use dumped JSON to reproduce issues ./target/debug/forge --conversation 2025-11-23_12-28-52-dump.json ``` ### 5. Clone Before Reproducing Bugs **Critical**: When a user provides a conversation with a bug, always clone it first: ```bash # Clone the conversation ./target/debug/forge conversation clone # This creates a new conversation ID - use that for testing ./target/debug/forge --conversation-id # Keep cloning the source until the fix is verified # Never modify the original conversation ``` **Why clone?** - Preserves original bug evidence - Allows multiple reproduction attempts - Enables A/B testing of fixes - Keeps source conversation clean ## Common Testing Patterns ### Test New Features ```bash # Build and test new command cargo build ./target/debug/forge --help # Verify new command appears ./target/debug/forge new-command --help # Check command docs ./target/debug/forge -p "test the new feature" ``` ### Reproduce Reported Bugs ```bash # 1. Dump the conversation (creates timestamped JSON file) ./target/debug/forge conversation dump # 2. Clone it for testing (preserves original) ./target/debug/forge conversation clone # 3. Reproduce with the cloned conversation ./target/debug/forge --conversation-id -p "reproduce the issue" # 4. After fix, verify with new clone ./target/debug/forge conversation clone ./target/debug/forge --conversation-id -p "verify fix" ``` ### Test Edge Cases ```bash # Test with missing arguments ./target/debug/forge command # Test with invalid input ./target/debug/forge -p "invalid task with special chars: <>|&" # Test with boundary values ./target/debug/forge -p "create a file with a very long name..." ``` ### Debug Prompt Optimization ```bash # 1. Dump conversation to analyze prompts (creates timestamped JSON) ./target/debug/forge conversation dump # 2. Review the conversation structure cat 2025-11-23_12-28-52-dump.json | jq '.messages[] | {role, content}' # 3. Export as HTML for easier reading ./target/debug/forge conversation dump --html # 4. Test modified prompts ./target/debug/forge -p "your optimized prompt here" ``` ## Integration with Development Workflow ### After Code Changes 1. **Build**: `cargo build` 2. **Docs**: `./target/debug/forge --help` (verify documentation) 3. **Test**: `./target/debug/forge -p "relevant task"` 4. **Verify**: Check output matches expectations ### Debugging a Bug Report 1. **Clone**: `./target/debug/forge conversation clone ` 2. **Build**: `cargo build` (with potential fixes) 3. **Test**: `./target/debug/forge --conversation-id -p "reproduce"` 4. **Iterate**: Repeat until verified 5. **Never commit** during debugging - only after full verification ## Quick Reference ```bash # Standard debug workflow cargo build ./target/debug/forge --help # Always check docs first ./target/debug/forge -p "your test task" # Dump conversation (creates timestamped file) ./target/debug/forge conversation dump # Output: 2025-11-23_12-28-52-dump.json # Export as HTML for review ./target/debug/forge conversation dump --html # Output: 2025-11-23_12-28-52-dump.html # Use dumped conversation ./target/debug/forge --conversation 2025-11-23_12-28-52-dump.json # Clone and test bug ./target/debug/forge conversation clone ./target/debug/forge --conversation-id -p "reproduce bug" # Debug prompts with jq (use actual filename) cat 2025-11-23_12-28-52-dump.json | jq '.messages[] | {role, content}' # Test with verbose output ./target/debug/forge --verbose -p "test task" ``` ## Tips - **Always `--help` first**: Get latest docs before testing - **Use `-p` for testing**: Don't test interactively, use prompts - **Clone conversations**: Never modify original bug conversations - **Never commit**: This is for debugging only - **Dump creates files**: `dump` automatically creates timestamped files (no `>` needed) - **HTML exports**: Use `--html` flag for human-readable conversation views - **Use relative paths**: Binary is at `./target/debug/forge` from project root - **Check exit codes**: Use `echo $?` to verify exit codes - **Watch for warnings**: Build warnings often indicate issues

debug-cli

Scan your own AI components