Rule: Before editing a fact that’s repeated in N+ canonical locations within a single document, enumerate ALL N locations FIRST. Then sweep all of them in one edit pass. Then grep-verify zero stale instances remain in operative-body content. Document the location-set in the CHANGELOG so future editors don’t repeat the miss.
Why: When a launch-prompt / plan / spec carries the same fact at multiple abstraction levels (frontmatter description + body intro + table row + step list + subsection detail + CHANGELOG entry, etc.), partial updates create split-personality drift — some sections present the new framing, others still present the stale framing. Executing sessions reading top-to-bottom inherit contradictory substrate; future-Claude reading frontmatter alone gets stale state. Empirical observation: this pattern recurred 3 times in the 6-commit Phase D” v1.0 → v1.5 launch-prompt refinement chain (v1.2 amend-request top-half-vs-bottom-half split; v1.4 launch-prompt §1.1-updated-but-frontmatter-stale split; v1.5 launch-prompt §1-intro-updated-but-§0+§2.A+§11-stale split). Each time, /review-plan caught the drift, requiring a follow-on micro-patch. Doing the enumeration upfront costs ~30 seconds; skipping it costs a ~10-15 min micro-patch + commit + verification cycle.
How to apply:
-
Identify the fact-class about to change: e.g. “Stage 3.5 dispatch mode” / “wall-clock estimate” / “version pin” / “lock status of D-N” / “subject of arch-state amendment A-NNN”. Pattern: any fact that an executing or reviewing session might look up in multiple places.
-
Enumerate canonical locations BEFORE editing. Common location-classes in TT launch-prompts (the 8-location pattern observed in Phase D” Stage 3.5):
- Frontmatter
description - Frontmatter
canonical_role - Frontmatter
purpose - §0 intro paragraph (just below the H1)
- §1 intro paragraph
- §1.1 totals line (e.g. “Total: ~Xh sequential; ~Yh wall-clock”)
- §1.1 stage-row content (per-row dispatch description)
- §2.A step list entry (per-step description)
- §11 top-level intro (for dispatch-orchestration sections)
- §11.B sub-section detail (operative-spec elaboration)
- §11.D.1 forward-question (if any; mark LOCKED when answered)
- §3.A done-criterion (for done-state changes)
- §4 Decision Matrix row (for fork/contingency changes)
- §10 CHANGELOG entries (carry historical framing — preserve, do not retroactively update)
- Frontmatter
-
Quick grep to enumerate:
grep -nE "<canonical-phrase>" <file>BEFORE the first Edit call. Treat each hit as a candidate location; classify each as “operative (must update)” or “historical (preserve)”. -
Edit all operative locations in the same commit. Use
replace_all: falsefor surgical patches per-location; this catches typos via the “exact match required” failure mode. -
Grep-verify after: re-run the same grep; confirm 0 stale instances remain in operative-body content. Document any historical-preservation exceptions explicitly (e.g. “3 historical instances retained at lines X / Y / Z”).
-
Document the location-set in the CHANGELOG entry: list the N locations + which were updated + which were preserved-as-historical. Future editors reading the CHANGELOG learn the pattern without having to rediscover it.
Concrete location-class patterns observed in TT documents:
| Document type | Recurring location-classes |
|---|---|
| Launch-prompts (~700L) | Frontmatter (description / canonical_role / purpose / phase_q_relevance / companion_files / tags) + §0 intro + §1 intro + §1.1 stages table + §2.A steps + §11 dispatch-orchestration (top-intro + .B detail + .D forward-questions) + §10 CHANGELOG (historical) |
| Amend-request / author-request dispatch-prompts (~400L) | Frontmatter + §0 “The prompt” intro + §1 “Scope” + §2 “Steps” + §13.6 grep-verify command + COMMIT MESSAGE TEMPLATE + SURFACE TO RICH section + CHANGELOG |
| arch-state.md amendments (when adding new amendment row) | §15 amendment registry row + §2.2-enumerated-cross-module count + §2.3-pending count + frontmatter lastmod + frontmatter companion_files pins (rare but check) |
| cascade-Q files (locking new Q-NNN) | Frontmatter companion_files floor-pins + §0 ANSWER blockquote + §1.1 PR opener + §3-§12 body content (canonical_state vs evidence vs commitments vs forward-questions) + §X CHANGELOG |
| BUILD-PLAN.md (per-repo) | §1 scope + §1.1 confidence-level + §2 per-repo stages + §3 step lists + §3.0/§3.0.5 substrate-pre-staging + §3.4 step assignment + §3.5 CI gate ratchet + §16 v6.6 coexistence (where applicable) + CHANGELOG |
| frontmatter-conventions.md (when adding new field / version bump) | §1 minimum-required-fields + §3.N field definitions + §4 status vocabulary + §5+ companion patterns + check-frontmatter-pins.py hook + CHANGELOG |
Counter-pattern to avoid: assuming “I’ve fixed the main location” without grep-enumerating. The whole point is that humans (including future-Claude) are bad at remembering every location a fact lives — the discipline COMPENSATES for that human-limit by making the enumeration explicit + mechanical.
When NOT to apply (acceptable single-location updates):
- Pure-historical record updates (CHANGELOG entries should NOT be retroactively rewritten — they’re frozen by their date)
- Frontmatter
v1_authoring_methodology_appliedor similar v1.0-historical-scoped fields (preserve) - One-off remarks in audit-records (audit-records are inherently single-point-in-time)
- Commit messages (single-shot; don’t sweep)
Empirical origin / case studies:
| Document | Commit | Pattern caught | Locations missed in original edit |
|---|---|---|---|
batch-imp-24-phase-d-double-prime-amend-request-v1.0.md v1.2→v1.3 | aef7273 | Top-half updated (gap-analysis + items list); bottom-half stale (§13.6 grep-verify command + COMMIT MESSAGE TEMPLATE + SURFACE TO RICH) | ~10 HIGH stale references |
batch-imp-24-bmad-openspec-hybrid-adoption-launch-prompt.md v1.3→v1.4 | 869aec1 | §1.1 stage rows + §4 Decision Matrix + §10 CHANGELOG updated; frontmatter (description / canonical_role / purpose / phase_q_relevance / companion_files / tags) stale; §11.B + §11.D.1 stale | 3 HIGH + 3 MEDIUM + 2 LOW + 2 GAPS |
batch-imp-24-bmad-openspec-hybrid-adoption-launch-prompt.md v1.4→v1.5 | 99c6109 | §1 intro paragraph updated per /review-plan C-2 spec; §0 intro + §2.A step 7 + §11 top-level intro stale (same Stage 3.5 dispatch fact at 4 abstraction levels) | 3 HIGH + 2 MEDIUM |
Related: feedback_review_plan_two_pass_pattern (the verification mechanism that catches split-personality drift); feedback_research_artefact_forward_traceability (the cross-document analog — references should be discoverable from multiple entry points); feedback_commit_message_must_match_frontmatter (sister discipline at commit-time); feedback_banner_sweep_grep_all_occurrences (similar grep-all-occurrences pattern for recurring banner phrases).
Substrate origin: Phase D” batch-imp-24 launch-prompt v1.0 → v1.5 refinement chain 2026-05-24 (commits 04b7872 → 99c6109; 6 commits; 1 arch-state amendment A-289; 0 hook bypasses; 3 split-personality patterns caught + swept). The v1.5 CHANGELOG entry documents the 8-location pattern for Stage 3.5 dispatch mode specifically; this memory generalises the discipline beyond Stage 3.5 to ANY repeated-fact edit.