elias/claw-code
1
0
Fork 0
mirror of https://github.com/ultraworkers/claw-code.git synced 2026-04-24 13:08:11 +08:00
Code Issues Packages Projects Releases Wiki Activity

roadmap(#180): file USAGE.md verb coverage gap

Browse Source 
Cycle #103 doc-truthfulness audit found USAGE.md incomplete.

Actual CLI has 14 standalone verbs (status, doctor, mcp, skills, agents,
export, init, sandbox, system-prompt, bootstrap-plan, dump-manifests,
help, version, acp).

USAGE.md covers only 3 entry modes (claw REPL, claw prompt TEXT,
claw --resume). Other verbs absent or underdocumented.

Example: USAGE.md says 'start claw, then /doctor' but doesn't explain
that 'claw doctor' is also a standalone entry point (no REPL needed).

Fix: Add 'Standalone commands' section to USAGE.md with all 14 verbs
documented. Include regression test (grep USAGE.md for each verb).

Doc-truthfulness family: #76, #79, #82, #172, #180.

Pinpoint count: 70 filed, 56 genuinely open.
This commit is contained in:
YeonGyu-Kim 2026-04-23 10:24:24 +09:00
parent de5384c8f0
commit e84424a2d3
1 changed files with 51 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

51
ROADMAP.md
View File

@ -10207,3 +10207,54 @@ claw --output-format json skills install .
**Status:** FILED. Per freeze doctrine, no fix on 168c.
**Pinpoint count update:** 69 filed (+1 from #179), 55 genuinely open.
## Pinpoint #180. USAGE.md incomplete verb coverage — doc-truthfulness gap — FILED (cycle #103, 2026-04-23 10:24 Seoul)
**Gap.** USAGE.md claims claw has 3 main entry modes but actual `--help` lists 13+ standalone verbs. Doc is **selectively truthful but incomplete**.
**Claimed in USAGE.md (intro section):**
```markdown
This guide covers the current Rust workspace under `rust/` and the `claw` CLI binary.
```
Then immediately jumps to "Quick-start health check" → `claw` (REPL) → `/doctor` (slash command).
**Actual --help output lists:**
```
claw help
claw version
claw status
claw sandbox
claw doctor ← REPL-less mode exists but USAGE.md calls it /doctor only
claw acp [serve]
claw dump-manifests
claw bootstrap-plan
claw agents
claw mcp
claw skills
claw system-prompt
claw init
claw export
```
That's 14 verbs not covered by USAGE.md's "quick-start" framing.
**Impact:**
- Users reading USAGE.md might think `claw doctor` only works inside the REPL
- No explanation of when to use `claw status` vs. `/status` vs. `--resume latest /status`
- `claw mcp`, `claw skills`, `claw agents` exist but aren't in the doc
- `claw export` is mentioned once at the end of the visible help but not in USAGE.md narrative
**Fix shape:**
1. Add "## Non-interactive verbs" or "## Standalone commands" section to USAGE.md
2. Document each verb: `claw status`, `claw doctor`, `claw mcp`, `claw skills`, `claw agents`, `claw export`, `claw init`, `claw sandbox`, `claw system-prompt`, `claw bootstrap-plan`, `claw dump-manifests`
3. Cross-reference with `--help` output for parity guarantee
4. Explain REPL vs. non-interactive trade-offs (session state, stdin handling, etc.)
**Family:** Doc-truthfulness family (#76, #79, #82, #172, #180). **First verb-coverage gap** (previous gaps were schema details).
**Regression test needed:** Docstring audit — `claw --help` output lines must be covered by USAGE.md somewhere. Could be a script that greps USAGE.md for each verb.
**Status:** FILED. Per freeze doctrine, no doc changes on 168c. Proposed separate branch: `feat/jobdori-180-usage-verb-coverage`.
**Pinpoint count:** 70 filed, 56 genuinely open.