debug-cli_skill

Overview

This skill provides a compact, practical workflow for debugging, extending, and verifying the forge CLI application. It focuses on safe iterative testing: build in debug mode, inspect help output, reproduce issues with conversation dumps, and clone conversations before modifying anything. The guidance is tuned for a Rust-based CLI development loop and emphasizes reproducibility and non-destructive testing.

How this skill works

The skill guides you to build the binary in debug mode, use --help to read current commands, and run tasks non-interactively with the -p flag to verify behavior. For conversation-related bugs it exports timestamped dumps (JSON or HTML), lets you clone the source conversation for safe reproduction, and shows patterns for reproducing and validating fixes without touching original data. It also covers edge-case tests and prompt optimization checks.

When to use it

• Adding or updating CLI commands, flags, or argument parsing
• Reproducing and diagnosing CLI behavior or exit-code issues
• Debugging conversation-handling bugs or LLM prompt regressions
• Testing new features quickly without committing changes
• Verifying fixes with safe, cloned conversation data

Best practices

• Always build with cargo build (debug mode) when testing changes
• Run ./target/debug/forge --help first to capture current docs
• Use -p for non-interactive tests; avoid interactive runs for repeatability
• Dump and clone conversations before reproducing bugs to preserve evidence
• Never commit debug-only changes; iterate until the fix is verified

Example use cases

• Add a new subcommand: build, verify it appears in --help, then test with -p
• Reproduce a reported LLM prompt bug by dumping the conversation and running with --conversation <dump.json>
• Fix argument parsing: run malformed inputs and boundary values to confirm errors and exit codes
• Optimize prompts by exporting conversation JSON, inspecting messages with jq, and testing modified prompts with -p
• Verify a fix by cloning the original conversation and rerunning the reproduction steps