mirror of
https://github.com/ultraworkers/claw-code.git
synced 2026-04-24 13:08:11 +08:00
docs: #155 — add USAGE.md documentation for /ultraplan, /teleport, /bughunter commands
## Problem Three interactive slash commands are documented in `claw --help` but have no corresponding section in USAGE.md: - `/ultraplan [task]` — Run a deep planning prompt with multi-step reasoning - `/teleport <symbol-or-path>` — 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 don't know: - What each command does - How to use it - When to use it vs. other commands - What kind of results to expect ## Fix Added new section "Advanced slash commands (Interactive REPL only)" to USAGE.md with documentation for all three commands: 1. **`/ultraplan`** — multi-step reasoning for complex tasks - Example: `/ultraplan refactor the auth module to use async/await` - Output: structured plan with numbered steps and reasoning 2. **`/teleport`** — navigate to a file or symbol - Example: `/teleport UserService`, `/teleport src/auth.rs` - Output: file content with the requested symbol highlighted 3. **`/bughunter`** — scan for likely bugs - Example: `/bughunter src/handlers`, `/bughunter` (all) - Output: list of suspicious patterns with explanations ## Impact Users can now discover these commands and understand when to use them without having to guess or search external sources. Bridges the gap between `--help` output and full documentation. Also filed ROADMAP #155 documenting the gap. Closes ROADMAP #155.
This commit is contained in:
parent
3cfe6e2b14
commit
4b53b97e36
39
ROADMAP.md
39
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 <symbol-or-path>` — 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 <symbol-or-path>`
|
||||
- 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.
|
||||
|
||||
54
USAGE.md
54
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
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user