{"slug": "show-hn-log-decisions-an-append-only-decision-journal-for-ai-agents", "title": "Show HN: Log-decisions – an append-only decision journal for AI agents", "summary": "A new open-source Agent Skill called log-decisions provides an append-only DECISIONS.md journal for AI agents to record consequential judgment calls, with decide/assume/escalate rules. The skill, compatible with Claude Code, Codex, Gemini CLI, and Cursor, was extracted from the swe-workflow repository (≤ v2.0.2) and is available under the MIT license. It aims to give agent-assisted work a durable, grep-able home for decisions that specs don't settle.", "body_md": "An append-only `DECISIONS.md`\n\njournal recording the consequential calls a spec didn't settle — what was chosen, by whom, and why, with decide / assume / escalate rules for what an agent may settle alone.\n\n**General-purpose.** The journal isn't coding-specific: any agent-assisted work — research, writing, ops, data — produces judgment calls someone will later ask *\"why was it done this way?\"* about. This skill gives those calls one durable, `grep`\n\n-able home at the repo root.\n\nIt ships as an ** Agent Skill** — pure markdown, no scripts — so it runs on\n\n**Claude Code, Codex, Gemini CLI, Cursor**, and any other skills-compatible agent.\n\n```\nnpx skills add swe-workflow/log-decisions\n/plugin marketplace add swe-workflow/log-decisions\n/plugin install log-decisions@log-decisions\n```\n\nThe skill ([ skills/log-decisions/SKILL.md](/swe-workflow/log-decisions/blob/main/skills/log-decisions/SKILL.md)) defines:\n\n**The bar**— if the spec already authorized the call it's not journal-worthy; if the agent had to invent the authorization, it is.** The 2×2**— classify each call as*determinable × reversible*, then**decide**(grounded by an artifact),** assume**(safe default, logged for async review), or** escalate**(stop and ask). A catastrophic floor — data loss, destructive migration, irreversible spend, public-interface breaks — always escalates.**The entry**— one append-only block per decision: Question, Options considered, Chosen, Decided-by, Justification, Outcome, with`Supersedes:`\n\nfor revisions. Never edited, never reordered.\n\n**Discussion**—[Show HN thread](https://news.ycombinator.com/item?id=49264597)** Claude Code plugin**— install with the commands above; submitted to Anthropic's[Plugin Directory](https://code.claude.com/docs/en/discover-plugins)(pending review)\n\n[ swe-workflow](https://github.com/swe-workflow/swe-workflow) — the idea → PRD → issues → ship suite — orchestrates this skill across every stage: spec-layer grills journal their assumed answers through it, and ship builds stage entries to a per-worktree\n\n`DECISIONS.staged.md`\n\npromoted at close-out. It was extracted from that repo (≤ v2.0.2) into this standalone one.MIT", "url": "https://wpnews.pro/news/show-hn-log-decisions-an-append-only-decision-journal-for-ai-agents", "canonical_source": "https://github.com/swe-workflow/log-decisions", "published_at": "2026-08-11 21:15:55+00:00", "updated_at": "2026-08-11 21:42:14.271650+00:00", "lang": "en", "topics": ["ai-agents", "developer-tools", "ai-tools"], "entities": ["log-decisions", "swe-workflow", "Claude Code", "Codex", "Gemini CLI", "Cursor", "Anthropic"], "alternates": {"html": "https://wpnews.pro/news/show-hn-log-decisions-an-append-only-decision-journal-for-ai-agents", "markdown": "https://wpnews.pro/news/show-hn-log-decisions-an-append-only-decision-journal-for-ai-agents.md", "text": "https://wpnews.pro/news/show-hn-log-decisions-an-append-only-decision-journal-for-ai-agents.txt", "jsonld": "https://wpnews.pro/news/show-hn-log-decisions-an-append-only-decision-journal-for-ai-agents.jsonld"}}