TT Claude Memory

feedback_live_state_files_first_framing

Properties1
descriptionWhen a discipline doc indexes both live state files (updated continuously) and snapshot specs (frozen-on-author-date), elevate live state files to primary "read-first" position; snapshot specs go to "historical context — not current truth"

3 min read

Rule: When a top-level discipline doc (CLAUDE.md, README, project ToC) indexes both live state files (architectural state files updated on every tension-lock) and snapshot specs (decision records frozen at the moment they were authored), the live state files MUST be elevated to the “read-first” primary position. Snapshot specs get demoted to “historical context — do NOT treat as current-state truth”.

Why: The opposite framing causes silent staleness across many repos at once. A reader who reads the snapshot spec first and trusts it as current makes decisions based on stale architecture. The live state files capture the canonical present — they’re the durable artefact. The snapshot specs are valuable for understanding rationale + decision history, but they fall out of date the moment they’re authored.

How to apply:

  1. Identify which docs are LIVE vs SNAPSHOT:

    • Live: name pattern *-state.md or *-state-*.md. Frontmatter includes update_trigger: listing what events bump it. Lastmod changes daily during active work.
    • Snapshot: name pattern includes a date prefix like 2026-04-19-*.md (URL-slug-style). Lastmod stable for weeks/months.

  2. Section ordering in the indexing doc:

    • First sub-section: LIVE state files (read-first; current truth)
    • Second sub-section: SNAPSHOT specs (historical context; NOT current truth)
    • Subsequent sub-sections: disciplines / version-meanings / cross-references / library / etc.

  3. Framing language:

    • Live: “These are the durable artefacts that reflect the architecture as it is RIGHT NOW. Updated on every tension-lock; carry the AUTHORITATIVE row.”
    • Snapshot: “Use for understanding rationale + decision history; do NOT treat as current-state truth.”

  4. Tier-1/2/3 framing (when applicable, e.g. arch-state hierarchies): list each tier explicitly with role + relationship + version-pin parenthetical (e.g. v3.10+).

  5. Cross-cutting state files (risk register / repo topology / standards engagement): list separately under a “cross-cutting” sub-heading after Tier-1/2/3 — they’re referenced by all tiers.

  6. Per-repo build plans (if multi-repo): list as a separate sub-section under live state — they bump independently of the architectural state files.

Anti-patterns:

  • Listing snapshot specs FIRST as “the canonical N” gives them status they don’t deserve. They’re frozen on author date.
  • Treating snapshot specs as current truth leads to decisions based on stale data (today’s session’s main risk-class).
  • Mixing live + snapshot in one list without distinguishing — readers can’t tell which to trust for current state.
  • Updating snapshot specs continuously (defeats their purpose; if state changes, update the live state file, not the snapshot).

Documented in: ~/.claude/CLAUDE.md §17.1 + §17.2 (canonical implementation reference) — applied 2026-04-29 via richard-tasks-tt.md #177; diff at ~/davieshq/docs-personal/global-claude-md-section-17-refresh-2026-04-29.patch. Pattern reusable for any future ToC reframe (e.g. project-level CLAUDE.md sections, README index reframes, docs-strategy ToC reframe).

Related discipline: feedback_architecture_state_file_discipline (which states “always read state files before producing strategic output”) + feedback_snapshot_vs_floor_pin_discipline (which captures the parallel snapshot-pin vs floor-pin distinction at the version-pin level).

Graph View

Backlinks