resume

Record where this session got to

A session record answers one question for whoever opens this repository next: what was in flight, and what was in the way. It is not a diary and it is not a changelog — the commit history already covers what happened.

When to write one

At the end of a stretch of work that did not finish. That is the case worth recording.

Do not write one when the work completed cleanly and left nothing outstanding — an empty record is worse than none, because the next session reads it and learns nothing while paying for it.

One record per session. If you are updating something you wrote earlier in the same session, edit that file rather than adding a second.

Where it goes

.chamnan/sessions/YYYY-MM-DD-short-slug.md

The date first, so the directory sorts chronologically and the newest record is the last line of an ls. The slug is a few words about the task, lowercase and hyphenated.

This is not STATE.md, and the difference matters:

.chamnan/STATE.md	one file, overwritten. What is true about this repository's work right now.
.chamnan/sessions/	many files, kept. Where a particular session got to and what it left.

Update STATE.md if the picture of current work changed. Write a session record if a stretch of work stopped partway. They are often both, and they are not the same file.

The format

# Short title of what you were doing

## Done
- What actually landed. One line each.

## Remaining
- What was next, specifically enough to pick up cold.

## Files
- `path/to/file.py` — what changed in it, in a few words

## Decisions
- What was decided and **why**. The why is the part that is expensive to reconstruct.

## Blockers
- What stopped progress, and what would unblock it.

Every heading is optional except the title. Leave out a section rather than filling it with a dash.

Write the identifiers out, every time

The one rule worth following even when it feels pedantic. A session record's whole job is to survive a gap — a compaction, a night, a different machine — and what a compaction destroys is specifically the identifiers. Measured: an LLM summarization pass recovers about 63% of facts, and the named failure is paraphrase — src/middleware/auth.ts:52 comes back as "the auth middleware file", and Error: ECONNREFUSED 127.0.0.1:5432 as "a database connection error". The sentence still reads correctly. The navigation is gone, and so is the ability to search for it.