--- name: tmchow/clawpatch source: https://app.decimal.ai/s/tmchow-clawpatch@1/SKILL.md source_sha256: ba8fa538c809 --- # Clawpatch — agent workflow > Clawpatch (`openclaw/clawpatch`, https://clawpatch.ai) is an agent-driven > CLI: it reviews a repo into structured findings and can apply validated > per-finding fixes. It needs a provider CLI (codex by default) and refuses > dirty worktrees. > > **This skill is judgment + orchestration, not a CLI reference.** For exact > flags, JSON fields, and exit codes, trust `clawpatch --help` and the > live `--json` output over anything written here — Clawpatch is pre-1.0 and > its surface drifts, so a written copy will mislead. What this skill carries > is what `--help` can't tell you: when to reach for it, how to fix findings > in parallel, and the traps. ## When to use Use Clawpatch when the user names it, or wants whole-repo automated review that yields locatable findings plus optional validated fixes. Don't use it for: a small diff already under review (a whole-repo review cycle is overkill — use a diff-review tool); a bug the user already understands and just wants written; or when no provider CLI (`codex`/`claude`/`cursor`/`grok`/ `opencode`/`pi`/`acpx`) is installed — `clawpatch doctor` fails fast, so say so and stop. ## Setup `clawpatch doctor` verifies the install and the provider. If `clawpatch` is missing: `npm install -g clawpatch`. The provider (codex by default) is the user's to install and authenticate — don't run login flows on their behalf. **Gitignore `.clawpatch/` up front — this is a prerequisite, not hygiene.** Once `init`/`review` write into `.clawpatch/`, an un-ignored state dir shows up as untracked files, which makes the worktree dirty — and `clawpatch fix` refuses to run on a dirty tree (exit 3). So ensure the repo's `.gitignore` contains the single line `.clawpatch/` *before* you review or fix, not after you hit the refusal (the line can be added even before `init`). It's a tracked file — confirm with the user before editing it. ## Review → findings The pipeline is `init → map → review → report`. `init` and `map` are local and cheap; `review` is the expensive step (~30–60s per feature with codex). For a first whole-repo pass, `clawpatch ci` runs that pipeline in one call and writes the same `.clawpatch/` findings the staged steps would — so "`ci` → pick a fix path" is a fine default. Drop to the staged commands only when you need to **sample before sweeping** a large or paid provider (`review --limit 3`, below), **scope to a slice** (`review --since `), or **resume an existing review** as code moves (`revalidate` / `review --since`, below). Either way `ci` **stops at findings — it never fixes or opens PRs**; fixing stays the paths under "Choose how to fix." Run `init && map` directly — they're **idempotent and non-destructive**, so an existing `.clawpatch/` just gets refreshed (`init` no-ops without `--force`; `map` re-classifies). No scan, no `--force`. `map` writes one JSON file per **feature** — the subsystem-sized unit (a package, a command, a service) that both review and scoping operate on — into `.clawpatch/features/`. State persists in `.clawpatch/` and there's no natural point where the agent deletes it, so findings — and their `fixed`/`wont-fix`/`uncertain` statuses — carry across runs. **That persistence is intentional: Clawpatch owns resume and freshness, so use its commands instead of hand-managing or wiping findings.** When code has moved since the last review: - `clawpatch revalidate --since ` (or `--all`) re-checks existing findings against the current code and updates their statuses — this is the CLI's de-stale mechanism. - `clawpatch review --since ` reviews only the features changed since ``, adding findings for new code without a full re-review. Prefer those over trusting stale statuses *or* wiping. Wiping (`[ -d .clawpatch ] && rm -r .clawpatch` — guarded, never `rm -rf`) is a last resort for genuinely corrupt state, not the freshness tool — it discards resume context and costs a full re-review. (There's no `--resume` flag; "resume" just means the on-disk state is still there.) On a large or unfamiliar repo, **smoke-test first** (`review --limit 3`) and treat that as often-sufficient — surface the time/cost before committing to a full sweep (`ci` or `review`). By default review sees only **committed** code; `--include-dirty` (on `review`, `ci`, and `revalidate`) pulls uncommitted worktree changes into scope — reach for it to review in-progress work before it's committed. It's a review-scope switch, not a `fix` dirty-tree override (Safety). ### Scoping the review The switches above scope *which code* review sees; this scopes *which features* it spends on. `review` has no path filter — you scope it by **selecting features**. Each `.clawpatch/features/*.json` carries an opaque `featureId` (a hash like `feat_library_…`, **not** a `1..N` index — passing a number silently matches nothing and the run reviews zero features) plus its `title` and `ownedFiles[].path`. To review only what the user named ("just the Go code", "only the auth package", "ignore the docs"), translate paths → ids yourself, then pass them — the flag repeats: ``` for f in .clawpatch/features/*.json; do jq -r '[.featureId,.title,((.ownedFiles//[])|map(.path)|join(","))]|@tsv' "$f" done # read the table, pick ids, then: clawpatch review --feature --feature … # confirm the flag in `review --help` ``` `--limit ` is the *cheapness* knob (first N features in map order) — right for a smoke test, useless for targeting an area; reach for `--feature` when the user names a subsystem. All Clawpatch state (features, findings, reports) is plain JSON under `.clawpatch/`, so read it directly when a `--json` payload is too large to scan or a wrapper truncates it. Read findings from `report --json`. The full flag set is `clawpatch report --help`; two non-obvious traps it won't flag for you: - `--json` writes the JSON to **stdout**; `--output` writes **Markdown**. Capture JSON by redirecting stdout (`> findings.json`), not `--output`. - The shape is `{ "findings": , "items": [ … ] }` — the findings are in `.items[]`, and field names drift from the docs (the id is `id`; evidence uses `path`/`startLine`/`endLine`). **Probe before parsing:** `jq 'keys, .items[0]' findings.json`. Each finding already carries fix-ready prose — `title`, `reasoning`, `reproduction`, `recommendation`, `suggestedRegressionTest`, `minimumFixScope` — ready to drop into a fix prompt or PR body. Ignore the `next:` hint Clawpatch prints; rank findings yourself (severity → confidence → triage), and never auto-fix without the user's pick (providers emit false positives). ## Choose how to fix: scanner-only vs full-cycle **Scanner-only (default, and the only safe parallel path).** Use Clawpatch purely as the reviewer; the host agent fixes findings with its own tooling. Required when the user wants fixes in parallel, the repo has strict commit/PR conventions, you want control over each patch, or the host model beats the provider's. **Full-cycle.** Let `clawpatch fix` produce and validate the patch. Fine for single-developer, sequential work in a low-ceremony repo where you trust the provider and want its format/typecheck/lint/test gate. The two are mutually exclusive — never run `clawpatch fix` from dispatched subagents (see Safety). ### Scanner-only dispatch 1. `init → map → review`, then `report --json > /tmp/findings.json`, in a throwaway worktree. 2. Pick findings to fan out; prefer ones whose `minimumFixScope`/evidence paths don't overlap, so subagents can't collide. 3. Per finding: extract its JSON (`jq '.items[] | select(.id==$id)'`) and dispatch a subagent in a **fresh worktree branched from `main`** (not the review worktree). Paste the finding JSON inline in its prompt. 4. The subagent fixes with the host's normal edit/test/commit/PR tooling and **never calls `clawpatch`**. Tell it to confirm the finding is real before changing anything (false positives) and to stay within `minimumFixScope` (no over-correcting). 5. The review worktree and its `.clawpatch/` are disposable — discard after. Don't reconcile fixed-status back into `.clawpatch/`; the audit trail is git (PRs, commit trailers). ### Full-cycle On a clean worktree, `clawpatch fix --finding `. On success the finding goes to `uncertain`, **not** `fixed` — confirm with `clawpatch revalidate --finding `. Then ship via `clawpatch open-pr --patch --draft` (Clawpatch writes a finding-rich PR body) or hand the diff to your own commit/PR flow. Check flags with `clawpatch fix --help`. Never run two `fix`es in parallel on one `.clawpatch/` (feature locks serialize them; interleaved patches don't merge). Stop and report on the first surprise: validation failure (exit 6 → `git restore .`), an oversized diff, or repeated `wont-fix`. ## Safety & pitfalls - **Never `--force` `fix`/`open-pr` without explicit user approval** — `--force` overrides the dirty-tree/validation guards. Clawpatch does **not** merge/land PRs today (there's no `land` command); if a merge/land command ever appears, treat it the same way — never run it without approval. - **Never combine subagents with `clawpatch fix`.** Sharing `.clawpatch/` across subagents risks patches landing in the wrong worktree (evidence paths resolve against the original `rootPath`); copying state per subagent is fragile. Pick one mode and stay in it. - **Don't blind-retry a non-zero exit.** Codes are typed (3 = dirty tree, 4 = provider auth, 6 = validation failed, 7 = lock → `clawpatch clean-locks`); `clawpatch --help` / the spec has the full set. - **Treat this doc as fallible.** Verify any flag, field, or exit-code detail against `clawpatch --help` and live `--json` output — they're the source of truth; this skill is the workflow around them.