Context clue	What to do
"current session"	Summarise all significant decisions/events from the conversation
"current changes" / staged files	Inspect `git diff --staged` or `git status`
"last N commits"	Run `git log -N --oneline` then read the diffs
"plan phase"	Read the plan file; summarise what was built and why
"PRD/plan completed"	High-level retrospective of the full feature
Specific topic stated by user	Use that topic directly

2. Interview until shared understanding

Before writing, confirm with the user:

What is the core topic? One sentence. If you can't say it in one sentence, it may be too broad.
What should be included vs omitted? Surface ambiguous areas and let the user decide.

The audience is always the author's future self — write to answer "why did we do this?" not to explain basics.

Keep iterating until both you and the user agree on what the entry covers.

Breadth check: If the draft outline covers more than ~3 distinct decisions or events, flag it:

"This is shaping up to cover [X, Y, Z]. Would you prefer one broad entry, or split into separate entries per topic?"

Respect the user's answer — do not force a split.

3. Gather evidence

Collect the raw material before writing:

Read relevant files, diffs, or plan phases
Note: decisions made and the alternatives that were rejected, bugs found and root causes, non-obvious constraints or discoveries, file/module paths that are central to the topic

4. Generate slug

Derive a short kebab-case slug from the topic (3–6 words max).
Examples: composite-key-routing, phase-3-job-complete, vat-rounding-bug.

5. Write the file

Path: docs/development-log/YYYY_MM_DD_<slug>.md
Use today's date. Create the directory if it doesn't exist.

Use the template below — keep sections that are relevant, omit the rest.

Entry template

---
date: YYYY-MM-DD
---

# <Title>

## Problem Statement

<Why this entry exists. What problem, situation, or question prompted it — from the developer's perspective. 2–4 sentences.>

## Solution

<What was built, fixed, or decided. Be specific. Include code snippets, config values, or file paths where useful.>

## Implementation Decisions

<A list of the key technical choices made. For each decision, include what was chosen and why. Cover:>

- Modules built or modified and their interfaces
- Architectural choices
- Schema or API changes
- Non-obvious constraints or discoveries

## Alternatives Considered

<Alternatives that were evaluated and rejected, and the reason each was ruled out.>

## Further Notes

<Result: what now works, what changed, what future work this enables or constrains, and any loose ends or follow-up observations.>

Tips

Prefer specificity. A narrow, focused entry ages better than a broad one — but broad entries are valid when the user wants a high-level summary.
One topic per entry is the default. If a session covered distinct decisions, offer to split.
Be specific. Vague entries ("we refactored the sync job") are worthless in 6 months. Name files, fields, and values.
Don't over-document. Skip obvious choices. Only record things that would be non-obvious to a future reader (including yourself).

dev-log

Dev Log

Quick start

Workflow

1. Determine scope and topic