decision-log is agent-read markdown (skill) from khaledsaeed18/dotclaude: Keep a lightweight decision log for a project or a person: one dated line per decision with the choice, the reason, the alternatives, who decided, and a revisit trigger, in a single Markdown file that is grepped rather than browsed, so that why did we do that has an answer six months later. Lighter than an ADR; use for product, process, and scope decisions that do not warrant one. Use when a decision is made in chat or a meeting, when the same debate keeps recurring, or when onboarding someone i.
Indexed from public GitHub and served as immutable, content-addressed versions. Install it pinned to an exact SHA-256 with the mdr CLI, and every file is verified against the hash recorded here before it reaches your agent. The deterministic audit below grades the latest version, and the same file always earns the same grade.
What the file says
An ADR is for architecture; most decisions are smaller (we will not support IE; the sprint is two weeks; the API uses cursor pagination; the thesis excludes mobile). They still get relitigated when nobody wrote them down. A decision log is the cheapest record that stops that: one file, one line per decision, appended and never rewritten.
## The file
`DECISIONS.md` at the project root (or `docs/DECISIONS.md`; match the repo), newest at the bottom so git blame and diffs stay readable:
```markdown
# Decision log
Format: date | decision | reason | alternatives | who | revisit when
- 2026-09-21 | Cursor pagination on all list endpoints | offset breaks under concurrent writes; clients already handle cursors | offset+limit; keyset only for large tables | API guild (A, B) | if a client cannot support cursors
- 2026-09-21 | Thesis scope excludes mobile clients | no access to a device lab; desktop covers 80% of sessions | include with emulators | K with supervisor | if the device lab opens before December
```
One line, under 200 words, no nested lists. Long reasoning links to a doc, an ADR, a ticket, or a meeting record.
## When to add a line
…
Pin to a label to follow the author's releases, or to a sha256 to freeze the exact bytes forever. Either way the resolved hash is written to mdr.lock, and mdr install reproduces it on any machine.
GET https://markdownregistry.com/api/v1/artifacts/art_qd5h2jnzcrzue44h
GET https://markdownregistry.com/api/v1/resolve?ref=khaledsaeed18/dotclaude/decision-log
GET https://markdownregistry.com/api/v1/blob/17c62fb5f4ed5051384dc1d6d9fba8e4ee0bbf6cf0692964fa315ee491d52c8c
Your agent does the legwork. You hear about the deals worth your word. Hand yours the standing instructions at modelranch.com and it joins the network that reads files like this one.
khaledsaeed18/dotclaude · .agents/skills/improve/SKILL.md · Survey any codebase as a senior advisor and produce prioritized, self-contained implementation plans for OTHER…
khaledsaeed18/dotclaude · .claude-plugin/plugins/docs/skills/adr-writing/SKILL.md · Write Architecture Decision Records that a future engineer can act on: a numbered, immutable record with the context…
khaledsaeed18/dotclaude · .claude-plugin/plugins/docs/skills/openapi-spec/SKILL.md · Write, generate, or review an OpenAPI 3.1 specification for an HTTP API so that it is accurate to the implementation…
khaledsaeed18/dotclaude · .claude-plugin/plugins/docs/skills/readme-writing/SKILL.md · Write or restructure a README that gets a reader from landing to first success in minutes: a one-line purpose, a…
khaledsaeed18/dotclaude · .claude-plugin/plugins/docs/skills/technical-writing/SKILL.md · Write and edit developer documentation, guides, design notes, and engineering blog posts with a working writer's…
khaledsaeed18/dotclaude · .claude-plugin/plugins/engineering/skills/adversarial-reviewer/SKILL.md · Review code through three hostile personas - the Saboteur, the New Hire, and the Security Auditor - each required to…
khaledsaeed18/dotclaude · .claude-plugin/plugins/engineering/skills/api-design-review/SKILL.md · Review an API contract (REST or GraphQL) before or while it is implemented, checking resource naming, HTTP semantics…
khaledsaeed18/dotclaude · .claude-plugin/plugins/engineering/skills/code-review-response/SKILL.md · Process code-review feedback with technical rigour. Understand each point, check it against the actual codebase, and…
khaledsaeed18/dotclaude · .claude-plugin/plugins/engineering/skills/db-migration-safety/SKILL.md · Review or write a database schema migration with production safety as the bar, checking locks, table rewrites…
khaledsaeed18/dotclaude · .claude-plugin/plugins/engineering/skills/dependency-upgrade/SKILL.md · Upgrade dependencies without breaking the project: audit what is outdated and why it matters (security, EOL, features)…
khaledsaeed18/dotclaude · .claude-plugin/plugins/engineering/skills/dockerfile-best-practices/SKILL.md · Write or review a Dockerfile and compose setup for a production service: multi-stage builds that ship only the runtime…
khaledsaeed18/dotclaude · .claude-plugin/plugins/engineering/skills/error-handling-patterns/SKILL.md · Design and review error handling in a codebase: which errors are expected results versus bugs, typed error hierarchies…
ulises-jeremias/agent-toolkit · plugins/agent-toolkit-complete/.github/skills/decision-log/SKILL.md · WHAT - Capture lightweight project, product, or operational decisions that do not require
broomva/skills · skills/strategy/decision-log/SKILL.md · Captures a decision with context, alternatives considered, and rationale, then links it to the relevant project doc in…
