diff --git a/ROADMAP.md b/ROADMAP.md index 3b70234..7968ae6 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -5960,3 +5960,42 @@ But USAGE.md documents that "The error message now includes a hint that names th **Blocker:** None. Pure error-message UX improvement. **Source:** Clawhip nudge 2026-04-21 21:37 KST — discovered during dogfood probing of model validation. + +## Pinpoint #155. USAGE.md missing docs for `/ultraplan`, `/teleport`, `/bughunter` commands + +**Gap.** The `claw --help` output lists three interactive slash commands that are not documented in USAGE.md: +- `/ultraplan [task]` — Run a deep planning prompt with multi-step reasoning +- `/teleport ` — Jump to a file or symbol by searching the workspace +- `/bughunter [scope]` — Inspect the codebase for likely bugs + +New users see these commands in the help output but have no explanation of: +1. What each does +2. How to use it +3. What kind of input it expects +4. When to use it (vs. other commands) +5. Any limitations or prerequisites + +**Impact.** Users run `/ultraplan` or `/teleport` out of curiosity, or they skip these commands because they don't understand them. Documentation should lower the barrier to discovery. + +**Fix shape (~100 lines).** Add a new section to USAGE.md after "Interactive slash commands" covering: +1. **Planning & Reasoning** — `/ultraplan [task]` + - Purpose: extended multi-step reasoning over a task + - Input: a task description or problem statement + - Output: a structured plan with steps and reasoning + - Example: `/ultraplan refactor this module to use async/await` +2. **Navigation** — `/teleport ` + - Purpose: quickly jump to a file or function by name + - Input: a symbol name (function, class, struct) or file path + - Output: the file content with that symbol highlighted + - Example: `/teleport UserService`, `/teleport src/auth.rs` +3. **Code Analysis** — `/bughunter [scope]` + - Purpose: scan the codebase for likely bugs or issues + - Input: optional scope (e.g., "src/handlers", "lib.rs") + - Output: list of suspicious patterns with explanations + - Example: `/bughunter src`, `/bughunter` (entire workspace) + +**Acceptance:** Each command has a one-line description, a practical example, and expected behavior documented. + +**Blocker:** None. Pure documentation. + +**Source:** Clawhip nudge 2026-04-21 21:47 KST — discovered discrepancy between `claw --help` and USAGE.md coverage. diff --git a/USAGE.md b/USAGE.md index dd74cf5..c8e7b09 100644 --- a/USAGE.md +++ b/USAGE.md @@ -125,6 +125,60 @@ error: no worker state file found at .claw/worker-state.json Then rerun: claw state [--output-format json] ``` +## Advanced slash commands (Interactive REPL only) + +These commands are available inside the interactive REPL (`claw` with no args). They extend the assistant with workspace analysis, planning, and navigation features. + +### `/ultraplan` — Deep planning with multi-step reasoning + +**Purpose:** Break down a complex task into steps using extended reasoning. + +```bash +# Start the REPL +claw + +# Inside the REPL +/ultraplan refactor the auth module to use async/await +/ultraplan design a caching layer for database queries +/ultraplan analyze this module for performance bottlenecks +``` + +Output: A structured plan with numbered steps, reasoning for each step, and expected outcomes. Use this when you want the assistant to think through a problem in detail before coding. + +### `/teleport` — Jump to a file or symbol + +**Purpose:** Quickly navigate to a file, function, class, or struct by name. + +```bash +# Jump to a symbol +/teleport UserService +/teleport authenticate_user +/teleport RequestHandler + +# Jump to a file +/teleport src/auth.rs +/teleport crates/runtime/lib.rs +/teleport ./ARCHITECTURE.md +``` + +Output: The file content, with the requested symbol highlighted or the file fully loaded. Useful for exploring the codebase without manually navigating directories. If multiple matches exist, the assistant shows the top candidates. + +### `/bughunter` — Scan for likely bugs and issues + +**Purpose:** Analyze code for common pitfalls, anti-patterns, and potential bugs. + +```bash +# Scan the entire workspace +/bughunter + +# Scan a specific directory or file +/bughunter src/handlers +/bughunter rust/crates/runtime +/bughunter src/auth.rs +``` + +Output: A list of suspicious patterns with explanations (e.g., "unchecked unwrap()", "potential race condition", "missing error handling"). Each finding includes the file, line number, and suggested fix. Use this as a first pass before a full code review. + ## Model and permission controls ```bash