Retro

Never re-derive a dead end twice. Record only knowledge future work cannot recover cheaply.

1. Scan the session

Ask:

• What took the longest?
• Which attempts failed, and why?
• What plausible approach was wrong?
• What environment/version/flag surprised us?
• What had to be rediscovered?

Also read the discipline report when installed: prefer local luciazero discipline --project . --json, then the checkout/package CLI. Use npx only when package resolution is explicitly allowed. A nudge or block is evidence, not cause; state any diagnosis as likely until repo evidence confirms it.

2. Filter hard

Keep only what reading the code cannot tell a future agent:

• Null results: measured no gain or broke another property.
• Footguns: an apparently correct action silently breaks something.
• Environment facts, ordering constraints, and why a tempting path is wrong.

Reject diff/history summaries, session-only values, and Anything a grep or --help answers. If nothing qualifies, stop: an empty retro is a valid result.

3. Route it, then write it

• Anyone who clones the repo: code/build behavior and disproven approaches. A debugged failure goes to docs/lessons.md:

  ## <greppable symptom; include exact error string>
  cause: <root cause> | proven-by: `<command>` | fix: <what fixed it> | date: YYYY-MM-DD

• True in every repository: append one deduplicated line to configured luciazero-heuristics.md under ${CLAUDE_CONFIG_DIR:-$HOME/.claude} or ${CODEX_HOME:-$HOME/.codex} for the active harness. Never include secrets or personal paths; cap the file at 100 lines and drop the weakest entry when full.
• Only this machine or this user: local paths, versions, preferences, and credential locations must never be committed. Use announced harness memory and update its MEMORY.md index when available. If no memory system exists, keep only a repo-true generalization; otherwise report the lesson without writing it.

Entry format:

- **<topic>** — tried <X>; failed because <Y>; do <Z> instead. (evidence: <line>, <date>)

Use the existing Project notes file (CLAUDE.md/AGENTS.md) for 1–2 load-bearing lines. Use docs/<topic>.md for detail and link it once. Follow existing conventions; do not create a parallel notes system.

4. Dedup and prune

Read destinations first. For an existing topic, update it in place. If evidence disproves an entry, correct or delete it. Apply this to project notes, docs/lessons.md, heuristics, and memory; a stale lesson mis-seeds future debugging.

5. Verify as a future reader

Read each entry as if six months later with no session context. Add the missing action/evidence or delete it. Report what was recorded, where, and what was deliberately not recorded and why.