feedback_cross_reference_discipline

Rich’s confirmation (Monday 20 April 2026): “i love this cross-referencing of documents — it feels like it is less likely for so many documents to go stale again in the future”

Context: after a day of interlocking updates (brand-architecture.md → Option G → scorecards → DADE doc → FHIR monetisation doc → partner-model.md) where each update carried specific version references to the other docs it touched, Rich explicitly validated the practice as net-positive for staleness prevention.

The rule: extensive cross-referencing with versioned pointers is the working practice. Do NOT scale it back.

What to do (operationalising the rule):

1. When citing another doc, always include its version. brand-architecture.md v1.13 not just brand-architecture.md. This makes stale citations visible — when you update the cited doc, every citer that references the old version becomes a candidate for refresh.
2. Cross-reference bidirectionally. If doc A cites doc B, doc B should cite doc A back (unless there’s a principled reason not to — e.g. B is the cross-brand canonical and A is brand-specific; then B points into a “Brand docs” forward-pointers section rather than individually).
3. Tag cross-refs in frontmatter related: field. Not just inline in the body. This lets grep-based tooling discover the relationship without reading every doc.
4. Supersession chains are explicit. If doc A supersedes doc B, A’s frontmatter has supersedes: with B’s path, and B’s frontmatter has superseded_by: with A’s path. Both ends marked.
5. Memory + ideas captures participate in the cross-reference graph. Memories cite canonical docs by version; ideas captures cite memories + canonical docs. When a decision flows memory → ideas → canonical doc, all three layers carry pointers to each other.
6. In new docs (e.g. future brands/*.md), carry forward the discipline from Day 1. §2 Cross-brand context row + §8 Pointers out row per the brand-docs template (filing-system spec v1.1) are both instances of this discipline.

Why it reduces staleness (Rich’s insight):

• A doc updated in isolation quickly becomes inconsistent with its neighbours — readers of the neighbours don’t see the update.
• With versioned cross-refs, updating doc A means: every doc that cites A’s OLD version has a grep-discoverable staleness marker. When someone touches doc B and sees “cites A v1.12” but A is now at v1.14, the discrepancy flags a potential refresh.
• Bidirectional cross-refs mean updates propagate in both directions — you don’t have to remember to update the downstream consumers; they’re visible in A’s related: and body cross-refs.
• The _archive_/ supersession discipline + ideas/ primary-evidence capture + memory index all participate — a session that lands in any one of these can navigate the network by cross-ref alone.

What to AVOID:

• Un-versioned citations (brand-architecture.md without a version number).
• One-way citations where bidirectional would work (doc A → B without B → A).
• “See the related docs” hand-waving without naming them.
• Updating a doc without also updating the downstream consumers that cite it (or at least flagging the staleness).

Sibling memories:

• project_three_track_badging.md — partner badging uses cross-ref-heavy references (Roadmap / Partner Model / InheritKit spec all cross-linked).
• Filing-system design spec docs/superpowers/specs/2026-04-19-filing-system-brand-docs-design.md v1.1 §2 captures the bidirectional-linking principle; brand-architecture.md v1.7+ added a forward-pointers table in §2 as the first canonical-doc implementation.
• feedback_ecosystem_not_dade_in_specs.md — confidentiality discipline that layers cleanly on top of cross-referencing (cross-refs use “Ecosystem” in spec contexts, partner-specific names in partner-dedicated docs).