From 0c7208a3fe3bdf6ecbb01076b64d0bb3f7da0025 Mon Sep 17 00:00:00 2001 From: Erik Date: Tue, 12 May 2026 18:22:40 +0200 Subject: [PATCH] docs(workflow): report-only-mode rules + retail-faithful-port guardrail in CLAUDE.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Three new bullets, all evidence-driven from /insights: "Only stop and wait for the user when": - Request is an investigation/audit/analysis/review/report-only — no edits or diagnostic drops until the user approves a fix. Use the /investigate skill (local at .claude/skills/investigate/SKILL.md, gitignored). - A referenced commit/path/branch/doc doesn't exist where the user said it would — ask one short question; don't go hunting across branches. Prevents the N.5-handoff-style 30-min wrong-branch exploration. "What NOT to do": - Don't replace working retail-faithful logic with a modern redesign without explicit approval. Cites the 267 min remote-entity rewrite + sky-fog shader speculation both reverted in full. Retail-faithful first; "cleaner" second. The /investigate skill itself stays local (option 3 — not committed). Co-Authored-By: Claude Opus 4.7 (1M context) --- CLAUDE.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index f88e77f..f4a9fcd 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -189,6 +189,14 @@ retail. Everything else is your call. files, reverting multiple commits) - Memory or committed history shows a clear user preference you're about to diverge from +- **The request is an investigation, audit, analysis, review, or "report-only"** + — no edits, no writes, no diagnostic code drops until you've delivered the + report and the user explicitly approves a fix. Use the `/investigate` skill + (`.claude/skills/investigate/SKILL.md`) to enter this mode cleanly. +- **A referenced commit, file path, branch, or doc doesn't exist** where the + user said it would. Ask one short question; don't go hunting across branches + or worktrees. A 1-line clarification beats 30 minutes of wrong-branch + exploration. **Things you should just do without asking:** @@ -348,6 +356,14 @@ isn't enough, attach cdb to a live retail client (Step -1).** context of the existing code it's modifying. The first animation sequencer integration was done by a subagent that didn't understand the transform pipeline — it broke everything. +- **Do not replace working retail-faithful logic with a modern redesign** + without explicit user approval. Two campaigns (267 min remote-entity + prediction+rubber-band replacing hard-snap; speculative shader edits in + the sky-fog work) had to be reverted in full because the redesign + regressed behavior the original port had right. When you see "I could + simplify this with X" on a retail-port, flag the tradeoff and ask + before deleting the existing path. Retail-faithful first; "cleaner" + second. ### Phase completion checklist: