Contract for the project decision journal (tradeoffs and lessons-learned logs). Use when recording a decision, tradeoff, or lesson, or building a consumer hook.
Installer avec Codex ou Claude Copiez ce prompt, collez-le dans Codex, Claude ou un autre assistant, puis laissez-le vérifier la page du skill et l'installer pour vous.
Une commande directe contourne le prompt de vérification. Examinez la source avant de l'exécuter.
Contract for the project decision journal (tradeoffs and lessons-learned logs). Use when recording a decision, tradeoff, or lesson, or building a consumer hook.
alwaysApply
false
model_hint
standard
Decision Journal Contract
When To Use
A workflow has just made a decision and needs to record the tradeoff:
what was chosen, what was rejected, what was sacrificed.
A workflow has hit a failed approach, rework, or blocker and needs to
record the lesson.
Building or validating a consumer hook that writes to the journal.
When NOT To Use
Scaffolding the files at project init (that is attune:project-init).
Recording a full architecture decision that warrants a numbered ADR in
docs/adr/; reference its number from a journal entry instead of
duplicating it.
This is a convention and a helper rather than a hard runtime
dependency. Consumers degrade gracefully when leyline is absent
(see Fallback).
What This Captures, And Why
AI-assisted work tends to narrate tool output ("the agent built X") and lose
the human reasoning: the decision, the road not taken, and the honest rework
nobody mentions. Two append-only logs, co-located with the code, fix that:
docs/tradeoffs.md records decisions and the alternatives sacrificed.
docs/lessons-learned.md records insights, failed approaches, and rework,
framed blamelessly.
Files And Discipline
Both files live in docs/ (co-location is the strongest anti-staleness
lever). Each is a single append-only running log with a scannable
## Active index at the top and an ## Archive section at the bottom.
Append-only. An accepted entry is never edited or deleted; only its
Status changes.
Supersede, do not overwrite. A reversal adds a new entry, flips the old
entry's status to superseded-by: <new-id>, and links both ways.
Stable IDs (TR-001, LL-001) so links from PRs, commits, and code
never break.
Every entry links back to its PR, commit, or issue.
The helper assigns the next ID, renders the template, inserts the entry above
the ## Archive marker, updates the active index, and (with --supersedes)
flips the prior entry's status and adds backlinks. It is idempotent: appending
an entry whose substantive fields already appear is a no-op.
Tradeoff fields
title (required), context, drivers (list), options (list of
{name, pros, cons, chosen}), decision, ystatement,
consequences_positive, consequences_negative, phase, deciders,
links. Prefer --json for the list-valued fields. status and date
are auto-set (proposed / today) but can be overridden.
Lesson fields
title (required), what_happened, what_went_well, what_didnt_work,
root_cause, action, category, owner, phase, links. status
and date are auto-set (open / today) but can be overridden.
Fallback (leyline Absent)
The entry template ships inside each scaffolded file as an HTML-comment footer
(<!-- ENTRY TEMPLATE ... -->). When the helper is unavailable, a consumer (or
a human) copies that block into the section above ## Archive, assigns the
next sequential ID, fills it in, and adds an index row by hand. The fallback
template covers the same core sections as the canonical one so entries stay
consistent across the two paths.
Consumer Hook Shape
Each workflow adds one block at its natural endpoint:
Record to the decision journal (draft + confirm):
- If leyline is installed: run journal_append.py for a {tradeoff|lesson},
drafting fields from this phase's context; show the draft; append on
confirm.
- Fallback (leyline absent): append to docs/{tradeoffs|lessons-learned}.md
using the footer ENTRY TEMPLATE; assign the next sequential ID.
