1. The brief

One sentence. Nothing more was needed: there was no platform decision to take, no plugin to write, no UI to design. The ask was for a discipline, not a feature. The only real questions were where the file lives, what it looks like, and how to keep it cheap enough that it actually gets written next time.

2. Why bother writing sessions down at all

Sessions move fast. By the next morning the small reasoning behind a decision is already gone — what was tried, what was rejected, what was deliberately deferred — and only the change itself is left in the codebase. The change tells you what; it never tells you why. A working journal closes that gap, in plain English, in the same project the work happened in.

There is also a second audience: the person who comes back to the project six weeks later, looking for a fix that was made and now appears to have unmade itself. The session log is the first place to look, because it is written like a memory, not like a commit.

3. The shape of an entry

Four short sections, in this order:

• Summary — one or two sentences on what was worked on.
• Decisions — anything we agreed to do, or deliberately not do.
• Changes made — what was actually updated, on the site or in the project.
• Follow-ups — anything left for next time.

The order matters. Summary first so a reader skimming dozens of files can decide which one to open. Decisions before changes, because a change without its decision behind it is the thing that ages worst. Follow-ups last, because they are the only section that asks the next session to do something.

4. Where the log lives

Inside the s2l-assistant project, a top-level folder called sessions-log/. One Markdown file per session, named by date:

sessions-log/
  README.md
  2026-04-28-session.md

Two-or-more sessions in the same day are disambiguated with a short label after the date, for example 2026-04-28-session-homepage.md. The label is just a hint — the title at the top of the file is still the source of truth.

The folder sits at the project root, not buried inside docs/ or .claude/, because the goal is for it to be the second thing a new collaborator notices after the README. Nothing about it is private; nothing in it is secret.

5. A short README to explain itself

A README inside sessions-log/ describes the convention in plain English: what the folder is, how files are named, and what each entry contains. Two paragraphs and a list. The README is deliberately short — long instructions go unread, and the format itself is simple enough to fit in a handful of lines.

6. The first entry, written same-day

To prove the convention works, the very first file in the folder is the entry for the session that set up the convention. It is brief by necessity — the session itself was an organisational one, not a code one — and that is part of the point. The format does not require a long entry to be a valid one. A short, honest entry is better than a long, padded one.

What that first file says, condensed:

• Set up a sessions log so we have a written record of what is discussed and done in each working session.
• Sessions log lives in sessions-log/ at the top of the project.
• Each session is saved as a dated file.
• Each entry has: summary, decisions, changes made, follow-ups.
• Created the folder, added the README, added the first entry.
• Nothing outstanding.

7. Going forward

From here on every working session ends with one extra step: a new file in sessions-log/, four short sections, written before the session is closed. When a session is rich enough to also warrant a permanent page on documentation.mobilearn.africa — like the lesson-descriptions session published the day before this one — the local Markdown stays as the raw note, and the docs page is the polished, longer-form retelling. The two are not redundant; they serve different readers.

The local file answers what happened. The docs page answers how it was decided and why. Both have a place.