Skip to content

Commit 4b53b97

Browse files
committed
docs: ultraworkers#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 ultraworkers#155 documenting the gap. Closes ROADMAP ultraworkers#155.
1 parent 3cfe6e2 commit 4b53b97

2 files changed

Lines changed: 93 additions & 0 deletions

File tree

ROADMAP.md

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5960,3 +5960,42 @@ But USAGE.md documents that "The error message now includes a hint that names th
59605960
**Blocker:** None. Pure error-message UX improvement.
59615961

59625962
**Source:** Clawhip nudge 2026-04-21 21:37 KST — discovered during dogfood probing of model validation.
5963+
5964+
## Pinpoint #155. USAGE.md missing docs for `/ultraplan`, `/teleport`, `/bughunter` commands
5965+
5966+
**Gap.** The `claw --help` output lists three interactive slash commands that are not documented in USAGE.md:
5967+
- `/ultraplan [task]` — Run a deep planning prompt with multi-step reasoning
5968+
- `/teleport <symbol-or-path>` — Jump to a file or symbol by searching the workspace
5969+
- `/bughunter [scope]` — Inspect the codebase for likely bugs
5970+
5971+
New users see these commands in the help output but have no explanation of:
5972+
1. What each does
5973+
2. How to use it
5974+
3. What kind of input it expects
5975+
4. When to use it (vs. other commands)
5976+
5. Any limitations or prerequisites
5977+
5978+
**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.
5979+
5980+
**Fix shape (~100 lines).** Add a new section to USAGE.md after "Interactive slash commands" covering:
5981+
1. **Planning & Reasoning** — `/ultraplan [task]`
5982+
- Purpose: extended multi-step reasoning over a task
5983+
- Input: a task description or problem statement
5984+
- Output: a structured plan with steps and reasoning
5985+
- Example: `/ultraplan refactor this module to use async/await`
5986+
2. **Navigation** — `/teleport <symbol-or-path>`
5987+
- Purpose: quickly jump to a file or function by name
5988+
- Input: a symbol name (function, class, struct) or file path
5989+
- Output: the file content with that symbol highlighted
5990+
- Example: `/teleport UserService`, `/teleport src/auth.rs`
5991+
3. **Code Analysis** — `/bughunter [scope]`
5992+
- Purpose: scan the codebase for likely bugs or issues
5993+
- Input: optional scope (e.g., "src/handlers", "lib.rs")
5994+
- Output: list of suspicious patterns with explanations
5995+
- Example: `/bughunter src`, `/bughunter` (entire workspace)
5996+
5997+
**Acceptance:** Each command has a one-line description, a practical example, and expected behavior documented.
5998+
5999+
**Blocker:** None. Pure documentation.
6000+
6001+
**Source:** Clawhip nudge 2026-04-21 21:47 KST — discovered discrepancy between `claw --help` and USAGE.md coverage.

USAGE.md

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -125,6 +125,60 @@ error: no worker state file found at .claw/worker-state.json
125125
Then rerun: claw state [--output-format json]
126126
```
127127

128+
## Advanced slash commands (Interactive REPL only)
129+
130+
These commands are available inside the interactive REPL (`claw` with no args). They extend the assistant with workspace analysis, planning, and navigation features.
131+
132+
### `/ultraplan` — Deep planning with multi-step reasoning
133+
134+
**Purpose:** Break down a complex task into steps using extended reasoning.
135+
136+
```bash
137+
# Start the REPL
138+
claw
139+
140+
# Inside the REPL
141+
/ultraplan refactor the auth module to use async/await
142+
/ultraplan design a caching layer for database queries
143+
/ultraplan analyze this module for performance bottlenecks
144+
```
145+
146+
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.
147+
148+
### `/teleport` — Jump to a file or symbol
149+
150+
**Purpose:** Quickly navigate to a file, function, class, or struct by name.
151+
152+
```bash
153+
# Jump to a symbol
154+
/teleport UserService
155+
/teleport authenticate_user
156+
/teleport RequestHandler
157+
158+
# Jump to a file
159+
/teleport src/auth.rs
160+
/teleport crates/runtime/lib.rs
161+
/teleport ./ARCHITECTURE.md
162+
```
163+
164+
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.
165+
166+
### `/bughunter` — Scan for likely bugs and issues
167+
168+
**Purpose:** Analyze code for common pitfalls, anti-patterns, and potential bugs.
169+
170+
```bash
171+
# Scan the entire workspace
172+
/bughunter
173+
174+
# Scan a specific directory or file
175+
/bughunter src/handlers
176+
/bughunter rust/crates/runtime
177+
/bughunter src/auth.rs
178+
```
179+
180+
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.
181+
128182
## Model and permission controls
129183

130184
```bash

0 commit comments

Comments
 (0)