From 79ea84a644d663b4f30d2e809e8f4280a4085413 Mon Sep 17 00:00:00 2001 From: Frank Ray <52075808+FrankRay78@users.noreply.github.com> Date: Sun, 13 Sep 2026 17:00:50 +0200 Subject: [PATCH] Capture learnings from #286 and #287 - /build stops when local main has unpushed commits: it branches from origin/main, so #281's study record, committed but never pushed, was silently missing from #286's branch. - Widen the grep-after-simplifying memory to the adding case: a new prompt rule must be reconciled with the older rules it overrides and scoped for every path it applies to. #286 and #287 both missed speckit.reviewissue's refine-run rules. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_016g3xHRn9ChW4mcjvduzB2U --- .claude/commands/build.md | 1 + .claude/memory/MEMORY.md | 2 +- .claude/memory/feedback_grep_after_simplifying.md | 9 ++++++--- 3 files changed, 8 insertions(+), 4 deletions(-) diff --git a/.claude/commands/build.md b/.claude/commands/build.md index 795ec06..4752a50 100644 --- a/.claude/commands/build.md +++ b/.claude/commands/build.md @@ -39,6 +39,7 @@ Two named exceptions, because `CLAUDE.md` requires discussion for them: - `git status --porcelain` is empty. If not, STOP: "Commit or stash your changes before building." A dirty tree would be swept into the issue's branch at step 4. - `git rev-parse --abbrev-ref HEAD` is `main`. If not, STOP: "Run /build from main — it creates the issue's branch itself." - `git fetch origin main` succeeds. + - `git log origin/main..main --oneline` is empty. If not, STOP: "Local main has unpushed commits — push or discard them before building." Step 4 branches from `origin/main`, so those commits would be silently absent from the issue's branch. 2. **Read the issue.** `gh issue view `. - If it is closed, or already has an open linked PR, STOP and say which — it is built or in flight. diff --git a/.claude/memory/MEMORY.md b/.claude/memory/MEMORY.md index 0feb31b..4db40a3 100644 --- a/.claude/memory/MEMORY.md +++ b/.claude/memory/MEMORY.md @@ -7,7 +7,7 @@ - [Prompts favour locality over DRY](feedback_prompts_locality_over_dry.md) — inline short rules in each slash-command prompt; skip canonical-section + cross-refs and defensive specs for cases the generator can't produce - [Codebase must not reference specs/ paths](feedback_no_spec_references.md) — specs are deleted post-merge; any `specs/-…` link in source/tests/docs becomes a dead reference - [Docs describe current codebase only — no forward references](feedback_docs_no_forward_references.md) — push back on task plans that mandate doc sections about unimplemented features tracked only by open issues -- [After simplifying, grep the whole repo for the removed concept](feedback_grep_after_simplifying.md) — diff misses stale comments and docs in files you didn't directly touch +- [After adding or removing a rule, sweep for what it touches](feedback_grep_after_simplifying.md) — grep for a removed concept repo-wide; reconcile a new prompt rule with older rules and re-run paths - [Don't introduce column-aligned whitespace in code](feedback_no_column_alignment.md) — single-space tokens; aligned blocks cause diff churn and break outside the editor - [Scratch and staging files belong in .claude/scratch/](feedback_scratch_file_location.md) — gitignored; not /tmp, not ~/.claude/, not a top-level .scratch/ - [Provider-agnostic types must not depend on concrete providers](project_dependency_direction.md) — Profile, SpeedUnit, etc. never reach forward into provider types; bridge lives on the provider side diff --git a/.claude/memory/feedback_grep_after_simplifying.md b/.claude/memory/feedback_grep_after_simplifying.md index bd4a334..91e204c 100644 --- a/.claude/memory/feedback_grep_after_simplifying.md +++ b/.claude/memory/feedback_grep_after_simplifying.md @@ -1,12 +1,14 @@ --- -name: After simplifying, grep for the removed concept's keywords -description: After dropping or simplifying a feature, grep the whole repo for the concept's keywords — the diff won't surface stale comments and docs in files you didn't directly touch. +name: After adding or removing a rule, sweep for what it touches +description: After removing a concept, grep the whole repo for its keywords; after adding a rule to a command prompt, search that prompt for older rules it overrides and every path it applies to. type: feedback --- After removing or simplifying a feature, grep for the concept's keywords across the whole repo — especially in files you didn't directly touch (docs, sibling tests, comment headers, project files, config files) — and update or remove every stale match. The diff alone won't surface them. -**Why:** Comments and docs in adjacent files are invisible to a code diff. When a concept disappears from one file, references to it elsewhere — `` blocks on related types, README snippets, doc comments on adjacent test classes, struct/class doc-comments — stay behind and rot silently. They survive code review because the reviewer is looking at the diff, not the rest of the repo. The next person to read those stale comments will be misled about how the system actually works. +After **adding** a rule to a command prompt, run the mirror-image sweep inside that prompt: find every older rule the new one overrides or qualifies, and reword those in the same change; and find every path the rule applies to (first run, refine/re-run, automated workflow) and scope it for each. + +**Why:** Comments and docs in adjacent files are invisible to a code diff. When a concept disappears from one file, references to it elsewhere — `` blocks on related types, README snippets, doc comments on adjacent test classes, struct/class doc-comments — stay behind and rot silently. They survive code review because the reviewer is looking at the diff, not the rest of the repo. The adding case is the same blind spot: in `speckit.reviewissue.md`, #286's new self-check clause was not scoped against step 6's refine-run rules, and #287's new Reason rule then contradicted the older quality bar and step 6 and was again not scoped to the refine run — both caught only by `/verify` reviewers (`docs/study/286.md`, `docs/study/287.md`). **How to apply:** - After any "remove feature X" or "drop concept Y" change, run a final sweep: @@ -14,3 +16,4 @@ After removing or simplifying a feature, grep for the concept's keywords across - Pay special attention to: `docs/` (especially `docs/architecture/*` and `docs/conventions/*`), README/USER_GUIDE files, sibling-feature `specs/` still in the tree, and XML doc comments / `` blocks on types whose code you didn't touch. - Treat the diff as **necessary but not sufficient** — comments and docs in adjacent files are invisible to it. - Simplifications driven by deleting speculative work tend to leave more stale comments than feature additions, because the dropped concept may have been described in many places before it was deleted from any one place. +- After adding a rule to a prompt, grep that prompt for the rule's subject (e.g. `Reason`, `refine run`, `step 6`) before committing, and reconcile every hit. See [[feedback_audit_class_after_two_failures]].