AI Skill Report Card
Managing Project Memory
Quick Start14 / 15
Three files live in the project root and carry memory between sessions:
- CONTEXT.md — what does not change: goals, people, where things live, settled decisions (with reasons), official numbers
- STATE_NOW.md — where things stand today: open loops with days-open counters, next actions, things that must NOT be done
- LEDGER.md — append-only log: what was done, decided, and checked, each entry dated
Two commands drive the workflow:
- Say "checkpoint" before ending a session or when it's getting long/degraded → agent writes current state into the three files.
- Say "resume" at the start of a fresh chat → agent reads only these files, runs a freshness check, reports status in ~15 lines, and gets to work.
Recommendation▾
Add an example of a stale resume where freshness check actually blocks progress until reconciled, to show the branch path fully.
Workflow14 / 15
On "checkpoint"
Progress:
- Scan the session for new decisions, numbers, or settled questions → append to CONTEXT.md with the reasoning, not just the conclusion
- Update STATE_NOW.md: close finished loops, add new open loops with today's date, revise next actions, note anything that must not be done (and why)
- Append a dated entry to LEDGER.md summarizing what happened this session (decisions, actions taken, checks run) — never edit past entries, only add
- Confirm all three files were written and are consistent with each other
On "resume"
Progress:
- Read CONTEXT.md, STATE_NOW.md, LEDGER.md only — do not reconstruct history from old chat scrollback
- Run the freshness check: compare file timestamps/dates against evidence of newer work (e.g., recent commits, newer file edits, dates mentioned in the repo). Flag if notes look stale
- If stale, say so explicitly and ask for a quick reconcile before proceeding
- Report status in 15 lines or fewer: current goal, where things stand, open loops (with days open), immediate next action
- Begin work from STATE_NOW.md's next actions
Recommendation▾
Include a minimal starter template/skeleton for each of the three files so Claude can scaffold a new project from scratch.
The 5 Rules That Stop Context Rot
- Decisions carry their reasons. Never record just "we chose X" — record why, so it can't be re-argued later from zero context.
- One official number, one place. Numbers that matter (budgets, targets, counts) live only in CONTEXT.md. Everywhere else references it, never restates it.
- LEDGER.md is append-only. History is never rewritten. If something changes, a new entry says so; old entries stay as the record of what was believed at the time.
- STATE_NOW.md is disposable and small. It reflects today only. Stale open loops get closed or explicitly carried forward with a day count — they don't silently accumulate.
- Fresh context reads memory files, not chat history. A new session's first move is reading the three files, never skimming old transcript for "what happened."
Examples17 / 20
Example 1 — Checkpoint mid-project Input: User says "checkpoint" after a session deciding to switch a data pipeline from batch to streaming. Output:
- CONTEXT.md gains: "Pipeline architecture: streaming (not batch). Decided 2024-06-03 — batch couldn't meet the <5min freshness SLA after client moved reporting to real-time dashboards."
- STATE_NOW.md updates: closes "evaluate batch vs streaming" loop, adds "migrate ingestion service to streaming — started, 0 days open", adds "do not touch the batch cron jobs until migration is verified."
- LEDGER.md appends: "2024-06-03 — Decided streaming over batch (SLA requirement). Began migration plan. No code changed yet."
Example 2 — Resume in a fresh chat Input: New chat, user says "resume". Output (15 lines):
Freshness check: STATE_NOW.md dated 2024-06-03, latest commit 2024-06-05 — notes are 2 days stale, confirm nothing major happened before I proceed.
Goal: migrate ingestion pipeline from batch to streaming (SLA-driven, see CONTEXT.md).
Open loops:
- Migrate ingestion service to streaming (2 days open)
- Validate downstream dashboard consumes stream correctly (0 days open)
Must not do: touch batch cron jobs until migration verified.
Next action: finish streaming consumer for the billing table, then run parity check against last known-good batch output.
Ready to continue — confirm the 2-day gap is fine or fill me in.
Recommendation▾
Clarify how to handle multiple concurrent open loops in STATE_NOW.md when several are stale at once (merge vs. list all).
Best Practices
- Keep CONTEXT.md short — if it's growing past a page, something belongs in LEDGER.md instead.
- Write LEDGER.md entries as if a stranger (or another agent) will read them cold — include enough context to stand alone.
- Run the freshness check every time, even if the user seems in a hurry — stale notes silently mislead more than no notes at all.
- Use one set of these three files per project; don't mix projects in one memory set.
- When handing off to a teammate or another agent, these three files are the handoff doc — no separate summary needed.
Common Pitfalls
- Don't let STATE_NOW.md accumulate dead open loops — close or explicitly re-date them every checkpoint.
- Don't edit or delete old LEDGER.md entries to "clean up" — append a correction instead.
- Don't record a decision in CONTEXT.md without its reasoning — that's exactly what gets re-argued three sessions later.
- Don't skip the freshness check just because the user said "resume" casually — stale context is worse than no context.
- Don't let official numbers drift into multiple files — one source of truth in CONTEXT.md, everything else points to it.