From e84424a2d3e8d565073adff853d5d2fe27f5865d Mon Sep 17 00:00:00 2001
From: YeonGyu-Kim <code.yeon.gyu@gmail.com>
Date: Thu, 23 Apr 2026 10:24:24 +0900
Subject: [PATCH] roadmap(#180): file USAGE.md verb coverage gap

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.
---
 ROADMAP.md | 51 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 51 insertions(+)

diff --git a/ROADMAP.md b/ROADMAP.md
index 0db5dd2..69a8215 100644
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -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.