From 0760c3664f2a9471f61089d42338314168ea061b Mon Sep 17 00:00:00 2001 From: viettranx Date: Tue, 14 Apr 2026 22:39:17 +0700 Subject: [PATCH] docs(claude): add plan verification rules for multi-phase workflows MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Encode 12 trust-but-verify checkpoints between scout → planner → final plan. Captures lessons from the elevenlabs-audio-manager plan audit: re-grep factual claims, re-scout on scope change, enumerate delete scope deep, verify external APIs via docs-seeker, cross-phase gates explicit, separate desktop/web scouts, i18n key ordering, signature caller enumeration, zero-coverage characterization tests, context key conventions, alias symbol coverage, and mandatory verify pass after rewrite. --- CLAUDE.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index 096b67d6..c7fd4ac4 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -184,6 +184,26 @@ Published to GHCR (`ghcr.io/nextlevelbuilder/goclaw`) and Docker Hub (`digitop/g - **Tool gating:** `TeamActionPolicy` in `internal/tools/team_action_policy.go` — lite blocks comment/review/approve/reject/attach/ask_user. `skill_manage`/`publish_skill` not registered in lite - **File serving:** 2-layer path isolation in `internal/http/files.go` — workspace boundary (all editions) + tenant scope (standard only with RBAC) +## Plan Verification Rules + +Apply before finalizing any multi-phase plan. Trust-but-verify between scout → planner → final plan. + +1. **Verify factual claims against code** — re-grep/re-count every number, path, endpoint. Don't copy from scout summaries. +2. **Re-scout on scope change** — if phase promotes from deferred → active, re-scout. Don't reuse brainstorm summary. +3. **Grep delete scope deep** — `grep -rn '' .` whole repo. Stubs often have refs in catalogs/routing/switch cases. Enumerate ALL sites in todo. +4. **Verify external API endpoints via `docs-seeker`** — before writing endpoint into plan. Sibling APIs often use different roots. +5. **Cross-phase gates explicit** — "Phase N-1 merged + tests green" in phase Context. Execution order alone ≠ enforcement. +6. **Scout desktop and web separately** — `ui/desktop/frontend/` ≠ `ui/web/`. Different structure, i18n namespaces, test framework presence. +7. **i18n keys ordering** — add key + 3 catalogs as explicit todo step BEFORE handler code. Missing key = runtime crash. +8. **Signature-change callers enumeration** — grep + list all callers explicitly. "Update all callers" insufficient. +9. **Zero-coverage characterization test = blocker step** — write byte/request-body fixture test BEFORE migration. Not "recommended". +10. **Context key style convention** — check existing `context.go` pattern before introducing new key types. Mixed = code smell. +11. **Alias/shim coverage** — enumerate ALL exported symbols via `go doc `. Add compile-time signature guards. +12. **Verify pass MANDATORY after rewrite** — spawn fresh Explore/grep to audit planner output. Don't trust self-validation. + +**Pattern to avoid:** user asks → planner writes → report "done". +**Safer pattern:** user asks → scout → planner writes → audit-verify → report. + ## Post-Implementation Checklist After implementing or modifying Go code, run these checks: