decision-journal
Decision journal (tradeoffs, lessons learned), deferred-capture contract ([Deferred] issues, CLI args, source labels), storage templates. Use to log a lesson.
Install / Use
npx skills add athola/claude-night-market --skill decision-journalInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
AutomationSupported Platforms
Tags
Our assessment of decision-journal
decision-journal scores 82/100 on our quality scale, 2303rd of 2,758 Automation skills we index.
Its SKILL.md is 6.6 KB long, well organised into 14 sections and no code examples: a thorough specification that gives an agent plenty to work with.
It has 338 GitHub stars, a meaningful sign that others use it.
Maintenance, license and trust
- The repository was last updated about 2 months ago, so decision-journal is actively maintained.
- It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 100/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands.
Automated pattern scan on 2026-11-22. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
decision-journal compared with similar skills
All 4 of these similar skills score higher than decision-journal; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| decision-journal (this skill)by athola | 82 | 338 | 59d ago | SKILL.md |
| Agent-Reachby Panniantong | 100 | 114.0k | today | CLAUDE.md |
| rufloby ruvnet | 100 | 82.3k | today | CLAUDE.md |
| Claude-Code-Game-Studiosby Donchitos | 100 | 40.6k | 12d ago | CLAUDE.md |
| Scraplingby D4Vinci | 100 | 104.9k | 5d ago | MCP Server |
Frequently asked questions
- How do I install decision-journal?
- Run
npx skills add athola/claude-night-market --skill decision-journal. The install tabs above show the steps for each supported agent. - Which AI agents does decision-journal work with?
- It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
- Is decision-journal safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. It is MIT-licensed and scores 100/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is decision-journal still maintained?
- The repository was last updated about 2 months ago, so decision-journal is actively maintained.
Skill content
View source on GitHubname: decision-journal description: Decision journal (tradeoffs, lessons learned), deferred-capture contract ([Deferred] issues, CLI args, source labels), storage templates. Use to log a lesson. alwaysApply: false modules:
- modules/deferred-capture.md
- modules/storage-templates.md
- modules/template-patterns.md
- modules/lifecycle-stages.md
- modules/storage-patterns.md
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.
- Building or validating a plugin's deferred-capture wrapper, or adding a
source label (load
modules/deferred-capture.md). - Choosing a template, maturity stage, or file name for stored knowledge
(load
modules/storage-templates.md).
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.mdrecords decisions and the alternatives sacrificed.docs/lessons-learned.mdrecords insights, failed approaches, and rework, framed blamelessly.
Files And Discipline
Both files are 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
Statuschanges. - 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.
Status vocabularies:
- Tradeoffs:
proposed -> accepted -> (superseded-by: TR-NNN | deprecated) - Lessons:
open -> actioned -> closed
Capture UX: Draft And Confirm
When a workflow reaches a decision or lesson point:
- Draft the entry from the live context of the phase (the options weighed, what was given up, the failure and its root cause).
- Show the draft to the human and let them confirm or edit.
- Append it. Tradeoffs start
proposed, and lessons startopen.
Do not auto-write without the confirm step. The point is to capture the human reasoning.
CLI Interface
Run the helper from leyline:
python3 ${LEYLINE}/scripts/journal_append.py <tradeoffs|lessons> \
--project-root <repo-root> \
--title "<short title>" \
[--phase <phase>] [--status <status>] \
[--field key=value ...] \
[--json '<full field object>'] \
[--supersedes TR-NNN] \
[--dry-run]
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.
Compliance Test
python3 ${LEYLINE}/scripts/journal_append.py tradeoffs \
--title "Compliance check" --field context="verify" --dry-run
Must print a rendered entry containing ## TR-001: and write nothing.
Related Contracts
modules/deferred-capture.md: the CLI, issue template, label taxonomy, duplicate detection, and JSON output that every plugin deferred-capture wrapper implements. Load it when building or checking a wrapper.modules/storage-templates.md: seedling, growing, evergreen, and reference templates, the promotion lifecycle, and naming conventions. Load it when organizing a knowledge store. Detail is intemplate-patterns,lifecycle-stages, andstorage-patterns.
Exit Criteria
- [ ]
docs/tradeoffs.mdanddocs/lessons-learned.mdexist with a## Active indexand an## Archivesection. - [ ] A new entry has a unique
TR-NNN/LL-NNNid and an index row. - [ ] Superseding an entry flips the old status to
superseded-by: <id>and adds bidirectional links. The old entry is not deleted. - [ ] Re-running the same append is a no-op (idempotency holds).
- [ ] A consumer with leyline absent still produces a correctly shaped entry from the in-file ENTRY TEMPLATE.
The last criterion holds even for consumers that name leyline in their
dependencies.
That field is marketplace metadata; no installer acts on it, so
spec-kit or imbue can be installed without leyline present.
The fallback guards that boundary. Do not remove it as leftover code.
See docs/metadata.md, "What dependencies Does Not Mean".
Related Skills
Agent-Reach
114.0kGive your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.
ruflo
82.3k🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
Claude-Code-Game-Studios
40.6kTurn Claude Code into a full game dev studio — 49 AI agents, 75 workflow skills, and a complete coordination system mirroring real studio hierarchy.
Scrapling
104.9k🕷️ The BEST Web Scraping framework that handles everything from a single request to a full-scale crawl! Don't be shy, join here: https://discord.gg/EMgGbDceNQ and follow here for daily tips and tricks: https://x.com/Scrapling_dev
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
