session-log

# Session Log Work spans sessions; context does not. Notes end up scattered — some in a context file, some in a README, some in a doc nobody opens — so neither the person nor the next assistant knows where to look. This skill fixes that with one fixed convention, installed once per project. After that, finding the notes no longer depends on this skill at all: any assistant that reads the repo's context file finds the pointer and knows where everything lives. That's the point — the convention has to survive being used by tools that never heard of it. ## The convention Four files, always the same names, always the same place: ``` docs/project/ status.md Where the work stands right now. Half-done things, next step, what's blocked, deployment state. VOLATILE — never loaded at startup. requirements.md What the system must do, and how you'd know it does. The contract. STABLE — loaded at startup. decisions.md What was chosen and why. Append-only, dated. STABLE — loaded at startup. context.md How the project is put together: documentation map, architecture, conventions, the traps that cost a day. STABLE — loaded at startup. ``` The split between `requirements.md` and `status.md` is deliberate and easy to get wrong. **The contract goes in requirements; the progress goes in status.** What a feature must do changes when the scope changes — rarely. Whether it's finished changes constantly. Putting them in one file means the contract gets rewritten every day, which invalidates the cached prefix behind it: the exact failure this convention exists to prevent. Fixed names are the whole point. A convention that adapts per project isn't a convention — it's the scattered-notes problem with extra steps. Someone opening any repo should know where to look without reading anything first. ### The client's vocabulary goes in the content, never in the paths Projects grow words: *modules*, *phases*, *blocks*, *deliverables*, *sprints*. Those words usually come from a conversation with whoever is paying — someone said "the work orders module" and it stuck. That's fine as a way to talk. It's a mistake as a directory structure. The moment the vocabulary becomes folders, two things happen. The layout stops being predictable across projects, because the next client uses a different word. And renaming becomes expensive, so the structure outlives the conversation that produced it — you end up with `docs/modulos/modulo-3-.../02-implementacion/` in one repo and `documentacion-importante/backend/` in another, both reasonable when they were created and neither findable from the outside. So: the four files are always the four files. Parts of the project are **headings inside them** — a section per module in `requirements.md`, a line per module in `status.md`. When the vocabulary changes, you edit a heading instead of moving a tree. This also keeps the depth. A project with real modules still gets a detailed breakdown; it just lives under a heading rather than a path. ### Never put the date in the filename `status-2026-07-21.md`, `resumen-avances-julio.md`, `progreso-etapa-1.md` — each one is a session that created a new file instead of updating the existing one. After a month there are twenty and none of them is *the current one*; finding out which is means opening several and comparing dates. That's the scattered-notes problem reappearing inside the folder that was supposed to solve it. The date goes **inside** `status.md`, at the top, and the file is overwritten. History is what git is for: `git log docs/project/status.md` gives you every past state, with its date, for free. The same applies to anything that sounds like a holding area — `to-review/`, `pending/`, `notes-temp/`. A file whose location says "somebody should look at this eventually" gets neither read nor deleted. Either it's current and belongs in one of the four files, or it's stale and should say so. ### When the project spans more than one repo A system with a web backend and a mobile client is one project in two repositories. Very often it's also **one working session**: someone adds an endpoint on the API side and, without switching context, wires the app that consumes it. The work is a single thought; only the folders are separate. **Install from inside each repo, separately**, and let each keep its own `status.md` — two repos have two branches, two deploy states and two histories, so one shared file goes stale on whichever side isn't being edited. Installing a repo's notes from its sibling means describing a project you're looking at from outside, and the result reads like it. **When a session touched both, close both.** This is the part that gets skipped, and it's where the two halves drift into separate realities: the mobile notes say "waiting on the API" for three weeks while the backend's notes never mention that anything is waiting. Write each side from what you did to it, not from what you assume about it — and if you couldn't reach the sibling, say that in the handoff instead of guessing at its state. A **monorepo** is the opposite case and takes the opposite answer — one `docs/project/` at the root, packages as headings — because one repo has one branch, one deploy and one history to describe. And `status.md` being rewritten whole every session makes it **conflict-prone the moment a second person or branch touches it**. All three cases, with the sibling header format, are in `references/file-layout.md`; none comes up on a project with one person and one branch, which is most of them. ### Why status.md is not loaded at startup Context files load at the start of every session, along with everything they import. Cached context is matched as a **prefix**: byte by byte from the start, and the first byte that differs invalidates everything after it. So a status line inside a startup-loaded file means every update to that line throws away the cache for all the stable content behind it — content that didn't change. The file you edit most often is the one that must not load at startup. There's a second reason. Stable context is *instructions*: it shapes how the assistant works. Status is *data*: it answers a question. Loading data as instructions every session costs tokens and dilutes the instructions that matter. `status.md` is read on demand — when someone resumes work and asks where things stand. That's cheap, and it's when the information is actually wanted. The same arithmetic catches `decisions.md` eventually. Append-only *and* imported only works while the file is young; after two years it's a long document loaded in full every session to answer a question nobody asked. Past roughly two hundred lines, everything but the current year moves to `decisions-archive.md`, which is not imported — nothing deleted, still searchable when someone needs it. `references/file-layout.md` has the mechanics. ## Installing it Write the same block into **every** context file the repo has. Not one; all of them. Different people and different tools read different files, and a note only one assistant can find is a note that disappears the day someone switches. The usual ones are `CLAUDE.md`, `AGENTS.md` and `GEMINI.md`, but the list keeps growing: `.github/copilot-instructions.md`, `.cursorrules` or `.cursor/rules/`, `.windsurfrules`, `CONVENTIONS.md`. Write into the ones that exist rather than creating new ones — a `GEMINI.md` invented for a repo where nobody uses Gemini is a file that will rot unread, and the point is to reach the readers who are already there. Keep the block short. Duplicated text drifts out of sync — three lines that say the same thing survive that; three paragraphs don't. ```markdown ## Project state - `docs/project/requirements.md` — what the system must do - `docs/project/context.md` — architecture and conventions - `docs/project/decisions.md` — what was decided and why - `docs/project/status.md` — where the work stands right now Read `status.md` when resuming work. Do not import it at startup: it changes constantly, and loading it invalidates the cached prefix behind it. ``` Import `requirements.md`, `context.md` and `decisions.md` if the tool supports imports; leave `status.md` out of every import chain. Then create the files with real content read from the repo, never placeholders — a template nobody filled in is worse than nothing, because it looks maintained. **Write the content in the language the project is already documented in.** The templates here are in English because the skill is; the files are for whoever opens the repo next. A `status.md` in English in a project whose README, commits and client conversations are in Spanish is a small tax on every future read, and the acceptance criteria are the part that suffers most — they're quoting what someone actually agreed to, and translating that loses the words the agreement was made in. File and section names stay fixed regardless; that's what makes them findable. ### Check that the location is actually tracked Before writing anything, confirm the target path isn't ignored: ```bash git check-ignore -v docs/project/status.md ``` Plenty of repos ignore `docs/` because they generate documentation into it. If that's the case here, the notes you're about to write will look fine locally and vanish on clone — the failure is silent, and it surfaces weeks later when someone else opens the project and finds nothing. Fixing it needs care: git can't re-include a file whose parent directory is excluded, so `!docs/project/` under a `docs/` rule does nothing. The pattern has to exclude the *contents* instead: ```gitignore docs/* !docs/project/ ``` If the repo ignores `docs/` for a reason you'd rather not touch, put the convention somewhere tracked and say where — a predictable location that exists beats a canonical one that doesn't. ### Tracked means published Being tracked is the point and also the risk: these files get committed, pushed, and on a public repo indexed. Session notes attract exactly what shouldn't travel — a token pasted while debugging, a staging URL with credentials in it, a client's phone number, the reason a particular customer is unhappy. Write around it. "The API key is in 1Password under *Gym staging*" carries the same information to the next session and none of the exposure; "blocked on the client's approval" says what's blocked without narrating a conversation someone would rather not find on GitHub. Anything that genuinely has to be verbatim belongs wherever the project already keeps secrets, pointed at from `status.md`. Git makes this expensive to undo — a secret deleted in a later commit is still in the history — so it's much cheaper not to write it. ### Map the documentation that already exists Before writing `context.md`, inventory what the project has documented: everything under `docs/`, plus `README.md`, `CONTRIBUTING.md`, and any spec or plan sitting elsewhere. Open each one far enough to say what it's for in a line. Then put that map in `context.md` as a section — one line per document, saying what it covers and when someone would need it. Not a file listing; a listing is what `ls` already does. The value is in "read this before touching X". This matters more than it looks. A repo usually has more documentation than anyone remembers, and the parts nobody remembers are functionally lost — the same scattered-notes problem, just with better-looking files. A doc that exists and isn't referenced anywhere will be rediscovered by accident or rewritten from scratch. Two rules while mapping: - **Reference, don't absorb.** A plan, a PRD, a numbered checklist has structure someone built on purpose. Point at it and say what it's for. Flattening it into `context.md` destroys the structure and creates a second copy that will drift. - **Say when it's stale.** If a document contradicts the code, that's worth a line in the map — "describes the v2 schema, superseded by decisions.md 2026-07-31". A map that presents rotten docs as current is worse than no map. Keep it current the same way: when a session adds or invalidates a document, the map gets a line. That's cheap, and it's what keeps the map trustworthy. Documents other tools generate belong in the map too, and they go missing fastest — an audit report, a migration plan, a design review, read once and then the stalest file in the repo. Map them **with the date they describe**: an audit of the codebase as it stood three months ago is a historical record, not a to-do list, and whatever survived from it should already be a line in `status.md` or an entry in `decisions.md`. **Migrating a project that already has notes elsewhere.** Move the content into the four files, then delete the old location and point anything that referenced it at the new place. Leaving both is how you get scattered notes again. Tell the person exactly what moved where. Templates and wiring detail: `references/file-layout.md`. ## Requirements: the denominator "What's left?" is unanswerable without knowing what finished looks like. That's what `requirements.md` is for, and it's the one file that lets you say how much remains without inventing a number. Most projects already have this somewhere — a PRD, a proposal, a numbered checklist, an email thread that got pasted into a doc. **Reference it, don't rewrite it.** `requirements.md` is an index: what the system must do, the acceptance criterion for each item, and a pointer to wherever the detail lives. If the project genuinely has nothing written, this is the file you write first — before any code, and often before there's a repo worth speaking of. An acceptance criterion is the useful half. "Payments work" isn't checkable; "charging a member writes a Payment row and the receipt shows the folio" is. When someone later asks whether a requirement is done, the criterion is what you verify against — and if you can't write one, the requirement isn't specified yet, which is itself worth recording. ### When there is no code yet Proposal, requirements gathering, design — the work is real and it's exactly where people forget where they left off, but there's no diff to verify against. Adapt rather than skip: `requirements.md` and `decisions.md` carry the weight, `status.md` records what the client agreed and what's still open, and verification runs against the artifacts that do exist — a requirement that says "as agreed in the proposal" can be checked against the proposal. Don't create empty files waiting for a phase that hasn't arrived; `references/file-layout.md` covers how to size this down. ## Which assistant did the work Months into a project a question comes up that none of the four files answers: what was this built with? It matters for a concrete reason — someone wants to reopen a piece of work by referring back to it, the way people refer to a conversation they had, and pick up a detail in the payments screen from last month. That only works in the tool that still holds the transcript. The intuition behind it is slightly wrong in a way that changes the answer, so it's worth being precise. The model remembers nothing between sessions; there is no continuity to return to. What exists is the **transcript, stored locally by the tool** — Codex keeps its own, Claude Code keeps its own, Gemini keeps its own, and none of them can read another's. So the thing worth recording is which tool was driving, with the model next to it, because the same tool behaves differently across models and the model is what you'd pick again. That belongs in `context.md`, and it earns a place in a startup-loaded file the same way the rest of that file does: it explains what the code doesn't say. A codebase whose scaffolding came from one assistant and whose auth rewrite came from another has two styles in it for a reason, and knowing that is the difference between "this is inconsistent" and "this had two authors". One row per **stretch of work**, never per session: | When | Assistant · model | What it produced | | --- | --- | --- | | 2026-06 | Codex · gpt-5.6-sol | Initial scaffolding, API layer | | 2026-08-17 | Claude Code · Opus 5 (`claude-opus-5`) | Auth rewrite, test suite | A row per session would grow without end and invalidate the cached prefix on every update — the one failure this convention exists to prevent. Add a row when a new assistant or model touches the project, or when one of them does something substantial enough that you'd want to return to it. Ten sessions of the same model on the same feature is one row whose date extends. `status.md` carries the volatile half: a `**Session by:**` line naming what wrote that note. It gets overwritten like the rest of the file, and `git log docs/project/status.md` then hands you the session-by-session history for free — which is why nothing has to accumulate anywhere. ### Record what the environment tells you, not what you infer An assistant is a poor witness to its own identity. The tool name and the model are usually stated somewhere concrete — a line in the system prompt, a `--model` flag, a config file — and that is what to write down. **When you don't have it, name the tool and leave the model out**, or ask. An invented model id is worse than an absent one, because it reads as something that was checked. `gpt-5.6-sol` and `claude-opus-5` are exactly the kind of string that looks verified whether or not it is, and months later nobody can tell which. Write the commercial name and the id when you have both — commercial names get reused across versions, ids don't — and always the date, which is what makes a wrong guess recoverable. ### If the continuation depends on a transcript, the record failed The table is a workaround, and mistaking it for the fix is the trap. Needing the original tool's transcript to continue means the reasoning behind that work exists only in a chat log: on one machine, inside one vendor's directory, unsearchable by anyone else and gone the day the project folder moves. That reasoning belongs in `decisions.md`, and the shape of the work in `context.md`. Do that and the table becomes a convenience — "this part came from Codex, which is why it's structured differently" — instead of the only way back in. A project any assistant can pick up is the goal; the table just says which one has the shortcut. Where each tool keeps its transcripts, and why Claude Code's are keyed to the project's absolute path — so moving the folder orphans them — is in `references/file-layout.md`. ## Which job this is Three jobs share this skill — install the convention, resume work, close a session — and the first has a variant worth catching before you write anything. Which one it is depends on the repo and on whether the person is arriving or leaving, not on how the request was phrased. Look before deciding: ```bash ls docs/project/ # installed already? ls CLAUDE.md AGENTS.md GEMINI.md CONVENTIONS.md \ .cursorrules .github/copilot-instructions.md # which context files exist ls -d .claude/memory .codex .gemini .cursor/rules # notes living somewhere else find docs -name "*.md" -not -path "docs/project/*"; ls README.md CONTRIBUTING.md ``` Read the output, not the exit status. These lines report "No such file" for whatever is absent, and that *is* the answer — but a command that failed on a missing path looks a lot like one that found nothing, and mistaking the two here is how you end up installing on top of a setup that already existed. **Nothing under `docs/project/`** — install the convention. Create the files that have content, fill them from what you actually read in the repo, add the pointer block to every context file found. If the third line turned something up, migrate it in and delete the old location; two places is the problem this solves. Say exactly what moved where, so the person can audit it. **Something that is almost this convention** — a single `docs/status/current.md`, or three of the four files under names someone chose by hand. That's an upgrade, not a fresh install: rename into the fixed names, fold the content into the right file, and update the pointer blocks that referenced the old paths. Treat the existing content as correct until the repo says otherwise — it was written by someone who was there. **Already there and the person is arriving** — resume. That's the next section, and it writes nothing unless they ask. **Already there and the person is leaving** — close the session: update `status.md`, and touch the other three only if something stable changed. That's "Closing a session", below. ## Resuming work "Where did we leave off?" is a read, and it's the moment `status.md` was written for. It's also where the file is most likely to lie — it's a snapshot of the day it was written, and nothing keeps it honest in between. Work landed, a branch got merged, someone deployed. Check it against the repo before repeating it back: ```bash git log -1 --format='%cd' --date=short -- docs/project/status.md # when it was last committed BASE=$(git log -1 --format=%H -- docs/project/status.md) git log --oneline "$BASE"..HEAD # what landed since git branch --show-current # versus the branch it names git status --short # what's uncommitted now ``` If `BASE` comes back empty the file has never been committed, so the date at the top of it is all you have — worth saying out loud, because an uncommitted `status.md` also means it exists on exactly one machine. Three kinds of drift are worth naming, because each one changes what to do next: - **Commits landed after it was written.** The "next step" may already be done. Say how many and from when instead of reading a stale plan as current. - **The branch moved.** A status naming `feature/payments` while HEAD is on `main` describes work that was merged, abandoned, or is sitting in a worktree — three very different situations, and the file can't tell you which. - **The tree is dirty in ways the file never mentions.** Uncommitted work from a session that ended without closing, which is the usual reason someone can't remember where they were. Then answer what was asked: where things stand, what's in flight, the next step, and which parts of the file you couldn't confirm. Keep it to what someone reads in fifteen seconds — they asked to be caught up, not to be handed the file back. If the drift is bad enough that the file misleads, say so and offer to rewrite it. Rewriting is a separate act and it's their call; arriving at a project shouldn't silently overwrite the record of how it was left. ## Closing a session The evidence comes first. Base what you write on this, not on recall of the conversation: ```bash git status --short # what's still uncommitted git log --oneline <base>.. # what landed git diff --stat # the shape of it ``` Write: **what changed** as outcomes, not a file list; **what's half-done**, naming which half works; **the next step**; and **what was verified versus assumed** — if tests ran, the numbers; if they never ran, say so, because an unqualified "done" that turns out to be untested costs the next session an afternoon. Three more things belong in `status.md` and are routinely left out: - **What's deployed, and since when.** Shipped and committed are different states, and on projects that deploy by file sync rather than by git they drift apart constantly — a file can be live on the server and uncommitted, or committed and never uploaded. Never infer one from the other. Record what you actually know, and say when you don't know. - **What's blocked by someone else.** A client who hasn't sent the copy, a store review, a provider whose sandbox is down. These read like pending work but can't be unblocked by working, so mixing them into the technical list makes the list lie about what's actionable. - **Which phase the project is in** — proposal, requirements, design, build, testing, live. One line. It tells whoever arrives which of these files matters today. Update `requirements.md`, `decisions.md` or `context.md` only when something genuinely stable changed: scope moved, a choice was made, a new document appeared, a different assistant or model took over a stretch of the work. Most sessions change nothing there, and that's normal. **When `status.md` grows, the cause is usually stable content that drifted in.** The test is simple: would this text be the same next week? A test checklist, an acceptance walkthrough, a list of platform-specific gotchas — those don't change between sessions, so they belong in `requirements.md` or `context.md` even though you're using them right now. Being *currently relevant* is not the same as being *volatile*, and confusing the two is how the volatile file ends up carrying half the project. The next step points at them: "run the acceptance walkthrough for requirements 13–18" is a next step. Pasting the walkthrough into `status.md` means rewriting it every session, which is both noise and the same cache problem in miniature. ### Follow the chain, not the checklist This is where a skill like this one can make things worse. A procedure followed carefully still produces a tidy record of a misunderstanding, and the failure looks like competence: correct format, specific file names, confident next step — resting on something that isn't there. Before writing a next step, follow what it depends on. A plan to add a refund route is worthless if nothing in the codebase ever persists a payment, and that gap is invisible if you're working down a list instead of reading the code. Ask what has to be true for the next step to be possible, then check that it is. When the code and the plan disagree, the code wins and the note says so. "The refund route can't be built yet — nothing writes a Payment record, so there's no id to refund against" beats a well-formatted plan built on sand. ### Recording finished work Check the claim before writing it down. Name the artifacts it implies, look for those specific things, record what you found, and report the evidence with the verdict — "found `PaymentGateway.php` and the `payments.*` routes" lets the person catch a wrong conclusion; a bare "✅" doesn't. Then **answer what was asked.** Someone asking you to mark work complete wants it marked, not a lecture on epistemics. Record the part that checks out and note the rest as open. Hedging everything into "implemented but unverified" and leaving the file untouched is refusing the request while appearing thorough. Per-stack specifics — Laravel, Titanium, Node, Python, Rails, Go — are in `references/verification.md`. ### Closing is not permission to edit You'll find real problems while taking inventory. Write them down and leave them. The uncommitted tree is the person's work in progress; a fix applied while they weren't looking is a fix they didn't review, landing in a diff they'll read tomorrow as their own. Same for publishing: don't commit their work, don't tag, don't push. Releasing assumes the work is finished, which is the opposite of why this exists. A log entry says "auth is half-wired, the form is missing"; a release note never says that. If the project has a release path — a `/release` command, a documented procedure — name it and stop there; deciding that this is the moment to run it is the person's call. **The four files are the exception, and skipping it is how this ends badly.** A session that writes `status.md` and walks away leaves the record uncommitted on one machine — invisible to the clone, to the next person, and to the next assistant. That is the scattered-notes failure this convention exists to prevent, reintroduced at the very last step. So finish by offering it in one line, naming which of the four you touched: *`status.md` and `context.md` are written but uncommitted — commit them?* Name them because a session that moved three of the four should not read as if only the status did. Don't run it unannounced, and don't leave without asking either. Once it's confirmed, stage the paths explicitly: ```bash git add docs/project/ # never -A: that sweeps in whatever they left half-done git commit -m "docs(project): session close YYYY-MM-DD" ``` If the tree was already dirty when you arrived, say so in the summary. A clean `git status` afterwards must not read as "everything is in". A release is the one case with no second ask. When the person runs `/release` or the project's documented procedure, the note is written **after** the tag — the release commit hash, the publish outcome and the published version don't exist before it — and its commit rides on the confirmation that procedure already collected. The same boundary holds in the other direction. `status.md` records that an audit found twelve issues and where the report lives; it isn't the place to fix them, and a session that quietly repaired three on the way past leaves a record that no longer matches either the report or the diff. ## Before finishing Resolve the import chain from each context file and confirm `status.md` isn't in it. This is worth checking every time rather than assuming, because it breaks quietly: someone adds an `@` line meaning well, and from then on every progress update throws away the cached prefix behind it — the one failure this convention exists to prevent. Check it, don't eyeball it — and check the files the inventory actually found, not a fixed list: ```bash grep -n 'status\.md' CLAUDE.md AGENTS.md # add whichever others exist grep -rn '^@' CLAUDE.md AGENTS.md # every import, including nested ones ``` A mention of `status.md` in the pointer block is correct and expected; an `@` line pulling it in is the failure. Follow each `@` to its target and grep that file too — the break usually happens one level down, where someone imported an index that imports everything. Naming a file that doesn't exist makes `grep` exit non-zero and print nothing, which looks exactly like a clean result. If you list `GEMINI.md` on a repo that has no `GEMINI.md`, you get silence and a failed command, and reading that as "no imports found" is how a broken chain ships as verified. Then close with a short summary in the person's language: where things stand, what's half-done, the next step, and the paths you wrote. Fifteen seconds of reading — the files hold the detail, and a handoff nobody reads is a handoff that failed.