docs(claude): add plan verification rules for multi-phase workflows

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.
This commit is contained in:
viettranx committed 2026-04-15 11:24:56 +07:00
1 parent b1b77597a9
commit 0760c3664f
1 file changed
+20
+20
View File
@@ -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 '<symbol>' .` 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 <pkg>`. 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: