/memory-discipline

name: memory-discipline
description: Use when recording lessons learned in a project, or when a project contains lessons/ or MEMORY.md — file-based memory format and read/write rules that measurably improve long-horizon performance.

Memory Discipline

Fable 5 performs notably better when it can write learnings somewhere for future reference. Give Opus the same surface and rules.

Read rules

• At the start of non-trivial work, read `MEMORY.md` (index) if present, then any

`lessons/*.md` whose one-line summary looks relevant.

• Memories reflect what was true when written — verify a referenced file/flag still

exists before relying on it.

Write rules

• One lesson per file in `lessons/`, kebab-case name, one-line summary on the first line.
• Record corrections from the user and confirmed working approaches alike — include WHY

it mattered, not just what happened.

• Don't save what the repo already records (code structure, git history, README facts).
• Update an existing lesson rather than creating a near-duplicate; delete lessons that

turn out to be wrong.

• After writing, add/refresh a one-line pointer in `MEMORY.md`.

Format

<!-- lessons/use-fake-clock-in-timer-tests.md --> Timer tests must inject a fake clock — real sleeps made CI flaky.

Context: PR #42 reverted twice. `time.monotonic` is patched via the `clock` parameter; never call `time.sleep` in tests.