A pattern for adding a decision layer to an LLM-maintained wiki.
Inspired by the LLM Wiki pattern proposed by Andrej Karpathy: persistent LLM-maintained markdown knowledge bases.
This is an idea file, designed to be copy pasted to your own LLM agent (e.g. OpenAI Codex, Claude Code, Cursor, OpenCode / Pi, or etc.). Its goal is to communicate the high level idea. Your agent should build out the specifics in collaboration with you, fitting the structure and conventions of your existing wiki.
The thesis: LLM-wikis help agents answer questions. But agents that create tickets, open PRs, draft campaigns, update processes, or operate tools need more than knowledge. They need a durable record of judgement.
An LLM-wiki helps an agent remember what you know. Decision Notes help it remember why you chose.
Most LLM-wikis organize information and knowledge: source summaries, entity pages, concept pages, contradictions, timelines, comparisons, synthesis.
But agents increasingly need to do more than answer questions. They recommend plans, create tickets, draft campaigns, open PRs, update processes, and operate tools.
For agents that act, knowledge needs a judgement layer.
They also need a durable record of judgement.
A Decision Note is a lightweight markdown file that records an important choice: what was decided, why it was decided, what evidence supported it, how confident you were, what alternatives were considered, what would make you revisit it, what actions should follow, and what happened later. Think of it as an ADR for LLM-wikis and agents: architecture decision records, generalized beyond architecture.
The flow looks like:
Sources -> Wiki Notes -> Decision Notes -> Agent Actions
This is loosely inspired by the DIKW framework: Data -> Information -> Knowledge -> Wisdom. LLM-wikis help organize information and knowledge; Decision Notes capture the judgement layer where knowledge turns into choices.
Sources preserve evidence. Wiki Notes organize knowledge. Decision Notes preserve judgement. Agent Actions should align with accepted decisions, subject to the agent's permissions and the user's approval rules.
Decision Notes are only meaningful when the agent has tools or workflows that can act on the decision, and when the wiki is the actual basis for that action. Valid decision categories should be derived from consequential actions the agent can recommend or take, not invented upfront.
Before proposing files, first inspect the wiki enough to understand its subject matter and operating purpose: the domain it covers, entities it tracks, recurring workflows it supports, available tools or actions the agent may take, and existing page types for facts, learnings, ambiguities, patterns, incidents, tasks, or proposals.
Then define what a "decision" means in this wiki. Do not assume Decision Notes are architecture decisions. A Decision Note should capture reusable judgement in the wiki's own domain: a choice, policy, recommendation, interpretation, prioritization, or operating rule that may shape future answers or actions.
Inspect the available tools. For each tool that represents a consequential action, such as filing a ticket, raising a PR, drafting a campaign, changing docs, triggering a deployment, or choosing not to take such an action, define whether that action needs Decision Notes. Do not create Decision Notes for classifications, routing logic, or standing rules; those belong in schemas, memory, or ordinary wiki pages.
Before creating templates or schema changes, propose the decision-note subject categories for this wiki. For each category, explain what action or non-action it governs, how it differs from existing wiki page types, when an agent should create one, whether it defaults to Proposed or can be marked Accepted, and what evidence is required. Ask the user to approve or revise these categories before implementation.
Add Decision Notes as a small layer inside or beside the wiki. Do not start with a database, app, JSON schema, knowledge graph, MCP server, task manager, or CLI unless the project clearly needs one. Start with markdown.
A simple structure:
decision-notes/
README.md
decision-template.md
examples/
example-decision.md
If the wiki already has a better place for this, use it. The important thing is that Decision Notes are linkable, visible from the wiki index, and connected to the pages and sources they depend on.
Use a template like:
# Decision: <title>
## Status
Proposed / Accepted / Superseded / Rejected
## Decision
What are we deciding or recommending?
## Context
What situation led to this decision?
## Evidence
Links to source notes, wiki pages, documents, conversations, metrics, or observations. Separate source-backed facts from interpretation. Do not invent evidence.
## Reasoning
Why does this decision make sense?
## Confidence
Low / Medium / High
## Alternatives considered
What else could we have done?
## Revisit when
What new information, metric, event, or date should trigger a review?
## Actions
What actions should follow from this decision, if any?
## Outcome
What eventually happened?Add YAML frontmatter only if the existing wiki already uses it. Useful fields might be type, status, date, confidence, tags, supersedes, and related.
Update the wiki's schema or agent instructions (AGENTS.md, CLAUDE.md, README.md, schema.md, or equivalent) so future agents know how to use Decision Notes. The schema should say where Decision Notes live, what template and statuses to use, when to create one, when to read existing ones, how to link evidence, how to update or supersede old decisions, and whether human approval is required before marking a decision as Accepted.
The key rule to add:
Before making recommendations, plans, or actions in an area that may already have decisions, read the relevant Decision Notes after reading the relevant wiki pages.
Decision Notes are read for alignment. Wiki pages are read for context.
Create. Create a Decision Note when a query, source ingest, discussion, or synthesis produces a choice that may matter later and can shape an agent recommendation, action, or deliberate non-action. Before creating one, classify the candidate decision by subject. Example subjects include strategy, product, architecture, research conclusions, customer/account decisions, process policy, agent behavior, evidence interpretation, and prioritization/resource allocation. These are examples only; adapt categories to the wiki's actual subject and available tools. If a future human or agent might ask, "Why did we do it this way?", create one.
Consume. Agents consume Decision Notes when answering questions, making recommendations, planning work, or taking tool-mediated actions. Before opening PRs, changing docs, creating tickets, drafting campaigns, or updating processes, the agent should check whether accepted Decision Notes authorize, shape, or block the action. If a proposed action conflicts with an accepted Decision Note, flag the conflict.
Update. When new evidence arrives, check whether it changes confidence, triggers a revisit condition, updates the outcome, or supersedes the decision. Do not silently rewrite history. If the decision materially changes, create a new Decision Note and mark the old one as Superseded.
Outcome. The feedback loop is the primary value. A Decision Note with no outcome recorded is incomplete. When a decision is overturned, corrected, or rejected by a human, record that verdict and reasoning; this is what calibrates future decisions.
Review. During wiki linting, scan Decision Notes for weak evidence, stale decisions, missing outcomes, conflicts, triggered revisit conditions, and proposed decisions that need human approval.
Index and log. If the wiki has an index.md, add a Decision Notes section with links, one-line summaries, statuses, confidence, dates, and related pages. If the wiki has a log.md, record when decisions are created, accepted, rejected, superseded, updated, or reviewed.
- Check relevant wiki pages first, then relevant Decision Notes.
- Align with accepted Decision Notes unless new evidence suggests they should be revisited.
- Treat proposed Decision Notes as recommendations, not approved decisions.
- Flag stale, weak, contradicted, or superseded decisions.
- Link Decision Notes to supporting wiki pages and sources.
- Do not invent evidence.
- Do not create a Decision Note just because something is interesting. Create one only when the wiki needs to preserve why a future recommendation, workflow, action, or interpretation should follow one path instead of another.
- Never treat Decision Notes as infallible. They are records of judgement, not eternal truth.
Help me add the smallest useful Decision Notes layer to this wiki. First inspect the existing structure, subject matter, schema, index, log, and representative pages. Then propose the decision-note subject categories and minimal files/schema changes needed. After approval, create the template, README, example, and index/log updates.
Keep it simple. Prefer markdown. Preserve evidence. Make decisions reviewable. Help the wiki move from knowledge to judgement to action.