Role
Keep, per ticket, a logbook that the developer rereads in one go before the MR or QA, and that an agent taking over the ticket reads to get back into context. Five contents: what was done, the decisions made, what remains to be done on the task, the production deployment actions, the points to know.
The log captures what evaporates: the why of the choices, the reversals, and the actions not to forget (migration to run, command to replay). The git log carries the what, the log carries the rest.
When taking over a ticket, read the log first — that is its raison d'être.
This skill does not relaunch itself as work goes on. For continuous writing, the project adds a rule to
its CLAUDE.md (e.g. "after each technical decision or completed task, invoke the skill dev-journal »).
Context
- Current branch: !
git branch --show-current - Date and time: !
date '+%F %H:%M' - Argument received: $ARGUMENTS
The file
- Location:
.task/<ticket>.journal.md..task/is a folder at the project root, reserved for working files per ticket. It can also contain a ticket outline written by the developer (.task/<ticket>.md); the log goes alongside it. Create.task/if missing. .task/is not versioned by default: add it to the project's.gitignoreif it is not there, unless the developer wants to share the log.<ticket>: first identifier matching the patternLETTRES-CHIFFRES(e.g.ABC-123) in the name of the current branch. Without an identifier, take the branch name with/replaced by-.- Created at the first entry if absent, from the template below — empty sections, without example bullets.
- A single writer on the agents' side: the main agent. Subagents do not write in it; the main agent records their useful conclusions at the moment it receives their report. The developer, for their part, writes whatever they want.
Template
# <ticket> — Journal de bord
## Ce qui a été fait
## Décisions
## Reste à faire
## Mise en prod
## À savoir
When to write
As it goes. Each entry is written at the moment the information appears, never in a catch-up pass at the end of the session.
| Moment | Section | Action |
|---|---|---|
| A technical decision is made | Decisions | Add a timestamped bullet at the end of the list (chronological order) |
| One decision replaces another | Decisions | Add the new bullet at the end of the list, strike through the old one (~~…~~) with the reference "replaced: see below" |
| A point to know appears | To know | Add the bullet immediately |
| Work remains on the task (development, tests, QA, commit) | To do | Add the checkbox immediately |
| An action is waiting for deployment (long migration, command to rerun, flag to enable) | Deployment | Add the checkbox immediately |
| A task is completed | What was done | Update the summary, task by task |
| The agent performs a checked action in To do or Deployment | The relevant section | Check the box; otherwise it stays with the developer |
A task is a delivered unit of work: a task from the plan .planify/ if a plan exists, otherwise a batch of
changes the size of a commit.
If $ARGUMENTS is not empty: record its contents in the relevant section (decision or need to know).
If it is empty: bring the log up to date from the conversation context.
The timestamp uses the date and time of the Context block; rerun date '+%F %H:%M' if several entries
are written at distant times in the same session.
Entry format
Decisions
One bullet per decision: - <date heure> — <choix> — <pourquoi en quelques mots>. A few words, not a paragraph.
- 2026-09-11 14:32 — Champ city sur Provider plutôt qu'une table Address — une seule adresse par tiers
- ~~2026-09-11 15:03 — Parsing des adresses en Python pur~~ (remplacée : voir plus bas)
- 2026-09-11 15:47 — Parsing des adresses via libpostal — les regex maison cassaient sur les adresses étrangères
To do
The remaining work on the task (development, tests, QA, commit). One checkbox per action:
- [ ] QA du formulaire tiers — modale de création depuis une facture étrangère
Deployment
The actions waiting for deployment, once the task is completed. One checkbox per action,
exact command in inline code, ready to copy:
- [ ] Lancer la migration 0042 — ~5 min sur la prod, table providers
Need to know
Informational only, simple bullet — an action to carry out goes in To do or Deployment:
- L'export garde l'ancien format tant que le feature flag est off
What was done
A few sentences, as a developer would explain it to a colleague — the overall what and the how, whereas the git log gives only isolated commit messages. A Mermaid diagram only if a diagram really helps (flow between components, sequence of states) — no diagram that paraphrases two sentences.
Guardrails
- Write short: short words, active voice, no figures of speech. The reader is a developer in a hurry.
- A decision without a why adds nothing — the why is the payload of the entry.
- Do not rewrite history: a cancelled decision is struck through, not deleted.
- The log replaces neither the ticket template nor a plan file — it complements them.