Compose Domain Knowledge Article

You are creating a piece of the project's institutional knowledge base — a living, browsable map that helps agents and humans understand not just what the code does, but what the person is trying to accomplish, what's proven, what's experimental, and what's unknown.

This is not documentation. Documentation describes machinery. This describes intent — what we want to be true, what evidence we have, and what's still uncertain. An agent consuming this learns to think in probabilities and evidence rather than assertions. The format itself is the training data for how agents should think.

Why this matters — the anti-hallucination argument

Here's the core problem. When you write "the email system uses provider X for transactional email" as a flat fact, every agent that reads it treats it as ground truth. If it's wrong, every feature an agent builds on top of that assertion is broken. That's a hallucination cascade. The documentation itself becomes a hallucination factory.

The /alignment-harness:align skill (if you have it) solves this for agent-human communication: never state an interpretation as a fact, always attach probability and evidence, nothing becomes shared reality until a human confirms it. This skill applies that same principle to documentation.

When you write "our intent with email is to optimize for engagement and churn reduction" — that's an intent, and it's either true or it isn't, and a human can validate it. When you write "we believe we measure this via X, with ~80% confidence because [evidence]" — an agent reading that knows not to blindly build on it. It knows to check.

Where articles live

All knowledge base articles go in <project>/docs/knowledge-base/{domain-name}/ — pick the project root you're actually documenting; don't assume any particular repo layout. If the project has no obvious docs location yet, ask once, or default to docs/knowledge-base/ at the project root and say that's what you did.

The knowledge base INDEX is at: <project>/docs/knowledge-base/INDEX.md

Linking: use plain markdown links ([text](path.md)) by default — they work everywhere. Only switch to Obsidian [[wikilinks]] if you've confirmed the person is actually keeping this knowledge base inside an Obsidian vault; a wikilink renders as dead bracket-text in every other viewer.

The output structure

The structure nests all the way down — substantive sub-domains get their own folders with their own INDEX.md and their own lifecycle children. Never merge substantive sub-domains into one big document.

Top-level domain structure:

{domain-name}/
├── INDEX.md                    ← Intent + map + links to sub-domain folders
├── {sub-domain-1}/             ← Each substantive sub-domain gets its own folder
│   ├── INDEX.md                ← Intent + map for THIS sub-domain
│   ├── validated/
│   │   └── proven-thing.md
│   ├── active/
│   │   └── current-system.md
│   ├── experiments/
│   │   └── hypothesis.md
│   └── open-questions/
│       └── unresolved.md
├── {sub-domain-2}/
│   ├── INDEX.md
│   ├── validated/
│   └── experiments/
└── deferred/                   ← Domain-level deferred items
    └── rejected-approach.md

Why nesting matters:

When everything is in one big doc, you can't reshuffle when things are ordered imperfectly. When sub-domains have their own folders, you can:

• Move an entire sub-domain folder without untangling it from other content
• Add or remove sub-domains without touching the parent
• Nest further — a sub-domain can have its own sub-domains if the complexity warrants it

How to identify sub-domains:

A sub-domain is a distinct concern within a domain that has its own intent, its own lifecycle items, and its own measurement surface. If removing it from the parent domain would leave a coherent gap, it's a sub-domain.

Example from a real project (opt-in, labelled — an email system for a coaching product):

• email-governance/ — the fail-open permission system, bounce guards, suppression rules
• email-engagement/ — re-engagement emails, scheduling, history-based content
• email-providers/ — which provider is used, migration status, contact management
• email-style/ — canonical design, inline HTML, what emails look like

A plainer, non-commercial example — an "authentication" domain:

• auth-sessions/ — how a session is created, refreshed, and expired
• auth-permissions/ — who can do what, and how that's checked
• auth-recovery/ — password reset, account recovery, locked-out flows

Each of these has its own intent, its own validated vs experimental items, and can be reshuffled independently. Not every project decomposes into "business domains" in the commercial sense — a domain can just as well be a system, a workflow, or a technical concern like "how errors get logged."

When NOT to create a sub-domain folder:

If a piece of knowledge is a single document (one validated fact, one experiment, one open question), it doesn't need its own folder. Put it directly in the parent domain's lifecycle folders. Sub-domain folders are for clusters of related knowledge that deserve their own INDEX.

The person can drag a doc from experiments/ to validated/ when it's proven. From validated/ to open-questions/ if it stops working. An entire sub-domain folder can be moved, renamed, or restructured without affecting siblings. The folder IS the status.

TOKEN BUDGET RULE (CRITICAL)

You MUST spend no more than 30% of your context on research and 70% on writing. If you find yourself reading more than 5-6 files or running more than 3 research queries, STOP RESEARCHING AND START WRITING. It is better to write an article with honest "~60% confidence, not verified" markers than to produce zero output because you exhausted your context on research.

The single biggest failure mode is: agent researches extensively, plans the structure, creates directories, and then runs out of context before writing a single file. DO NOT DO THIS. Write files as you go — after each sub-domain is researched, write its files immediately before moving to the next sub-domain.

How to think before writing (your process, not the output)

Before you write a single word of a domain article, you need to do the work that prevents hallucination. This is your internal process — it does NOT appear in the output document. The output is optimized for human consumption. But if you skip this process, your output will be full of assertions that sound confident and are wrong.

Step 1: Understand the intent of this domain

What is this domain trying to accomplish for the business or project? Not "what does the code do" — what human experience is this domain serving? What relationship with users does it create?

If a memory-search or intent-database tool is configured for this project (see /alignment-harness:harness-setup), search it for the domain name and keywords like "intent", "goal", "why". Otherwise, search the project's own docs, plans, and README files, and grep git log for the domain's name to see what decisions were made and why. Read any existing seed documents or plans.

You're looking for: what do we WANT to be true about this domain? Not what IS true in the code.

Step 1b: Boost certainty with an institutional-knowledge oracle (if one is configured)

If you have /alignment-harness:insight (or an equivalent oracle) set up, run it before drafting anything: skill: "insight", args: "What principles, past learnings, and decisions apply to [domain name]? What has gone wrong in this domain before? What matters most?" If your certainty on any aspect of the domain's intent is below 90%, run it again with a more specific question.

If no oracle is configured, skip this step and say so in the article — note in the "Related plans and initiatives" section that no oracle was available, rather than silently proceeding as if this step happened. This is not a blocker: write the article from code, project docs, and a live conversation with the person instead. It will carry lower confidence markers than it would with an oracle behind it, and that's the honest state to record, not a reason to produce nothing.

Include insights that changed your understanding, with a note about what the oracle surfaced, when one was used.

Step 2: Research what exists

Now — and only now — look at what actually exists. But do NOT treat what you find as fact. Treat it as evidence at a probability level.

Research sources, roughly in order of reliability (this ranking is a starting default — recalibrate it once you've used your own setup for a while and know which sources actually hold up):

1. Code you read in this session — highest reliability (~90%), but code changes daily
2. Person-confirmed statements (in a project's CLAUDE.md, a confirmed-intent doc, or direct conversation) — very high (~95%)
3. Institutional-memory search results, if configured — useful context but may be stale (~70%)
4. Session compactions / saved session summaries, if you keep them — capture conclusions but not reasoning (~65%)
5. Any supplementary memory store — compactions or the project's own docs are canonical over this (~60%)
6. Your own prior knowledge — lowest reliability, ceiling of 50% without verification

For each piece of information you find, note:

• What source it came from
• When it was last verified (date if available)
• What confidence level you'd assign it
• What would break if it's wrong

Step 3: Find the related material

Search for everything connected to this domain:

• Plans — wherever the project keeps planning docs (e.g. docs/plans/)
• Seeds — any early-stage idea docs the project keeps
• Measurements — How do we measure whether this domain is working? What KPIs, experiments, dashboards exist?
• Correction patterns — What have agents gotten wrong in this domain before? Check institutional memory if configured, or grep past session transcripts / commit messages for corrections
• An intent database, if the project keeps one — what UX or product intents relate to this domain?
• Meta-analysis docs — a docs/meta-analysis/ folder, if the project has one, may have deep-dives
• Research artifacts — a memory search, if configured, may surface cached research from past sessions

Step 4: Identify the lifecycle boundaries

Which pieces of knowledge are:

• Validated — confirmed by the person or proven by consistent evidence across sessions
• Active — currently running in the system, working as far as we know
• Experimental — being tested or proposed but not validated
• Open questions — unresolved, nobody has decided
• Deferred — we looked at it and chose not to pursue (with reason)

These categories become the folders. Each piece of knowledge becomes a separate document in the appropriate folder.

How to write the INDEX.md (the parent document)

The INDEX.md is the map. It leads with intent, shows the landscape, and links into the lifecycle folders. It does NOT contain detailed knowledge — that lives in the child documents.

Structure:

# {Domain Name}

> The intent of this domain, the map of everything related to it, and links to the knowledge in its current lifecycle state.

---

## Intent

{What are we trying to accomplish with this domain? Not what the system does — what human experience are we trying to create? What relationship with users? Why does this matter in the context of the project?}

{This section should feel like the person explaining to a new team member why this domain exists and what it's for. Written in human language, no variable names, no jargon.}

---

## How we want to relate to {users/agents/the project} through this domain

{The deeper intent. Not just "what" but "how" — what quality of experience, what values, what approach. This is where the nuance lives that prevents agents from technically satisfying requirements while missing the point.}

---

## The map

### Sub-domains
{List each substantive sub-domain with a link to its INDEX.md and a one-line description of its intent}

- [sub-domain-1/INDEX](sub-domain-1/INDEX.md) — {one line: what this sub-domain is trying to accomplish}
- [sub-domain-2/INDEX](sub-domain-2/INDEX.md) — {one line: what this sub-domain is trying to accomplish}

### Domain-level items (things that don't belong to a specific sub-domain)

#### Validated — things we know work because they've been confirmed
- [doc-name](validated/doc-name.md) — {one line: what it is, who confirmed it, when}

#### Active — things currently running in the system
- [doc-name](active/doc-name.md) — {one line: what it is, operational status}

#### Experiments — things being tested or not yet validated
- [doc-name](experiments/doc-name.md) — {one line: what it is, confidence level, what's being tested}

#### Open questions — things nobody has decided yet
- [doc-name](open-questions/doc-name.md) — {one line: what the question is}

#### Deferred — things we chose not to pursue (yet)
- [doc-name](deferred/doc-name.md) — {one line: what it was, why deferred}

---

## Related plans and initiatives

- {Link to plan docs, seed docs, proposals — anything that represents future or in-progress work on this domain. If an oracle or memory search surfaced something here, say so.}

---

## How to audit this domain

{Instructions for an agent that wants to check whether reality matches intent. What to read, what to check, how to compare intent vs actual, what to do when they find a gap.}

How to write child documents

Each child document lives in its lifecycle folder and follows a structure appropriate to its type.

Validated documents

# {Thing Name}

> **Lifecycle:** Validated
> **Confirmed by:** {who, when}
> **Evidence:** {brief — what makes us confident}

---

## Intent

{What is this thing trying to accomplish?}

## What happened / How it works

{The substance. Written as narrative, not assertions. "The person said [quote]" not "This is how it works." Evidence attached to claims.}

## What depends on this

{What other things in the system assume this is true? This is critical — it tells you the blast radius if this turns out to be wrong.}

## Where this lives

{File paths, endpoints, skills — but framed as "I believe this lives at X" if not verified in this session}

## What could make this stop being true

{What would invalidate this? Code changes, config changes, dependency updates?}

Experiment documents

# {Experiment Name}

> **Lifecycle:** Experiment
> **Status:** {proposed / in-testing / results-pending}
> **Confidence that this would help:** ~{N}%
> **Evidence:** {what we're basing the confidence on}

---

## Intent

{What is this experiment trying to learn or prove?}

## What we think might be true

{The hypothesis, framed as a hypothesis — not as fact.}

## What we don't know

{Explicit gaps. What would need to be true for the hypothesis to hold? What could disprove it?}

## What exists in code

{If anything has been built. File paths with confidence levels.}

## What would need to happen to validate this

{Specific steps to test the hypothesis. Not vague — concrete.}

## What depends on this

{Usually nothing — experiments should be safe to fail. But note it if something does depend on this.}

Open question documents

# {Question}

> **Lifecycle:** Open question
> **Status:** Nobody has decided this yet
> **Confidence that this is worth pursuing:** ~{N}%

---

## The question

{State it clearly. One question.}

## Why this might matter

{What would change if we had an answer?}

## Why this might not matter

{Is it possible the question is irrelevant? Under what conditions?}

## What would need to happen to explore this

{Concrete steps to investigate. Not "think about it more" — what data, what experiments, what conversations.}

## What depends on this

{Usually nothing — if something depends on an unresolved question, that's a problem to flag.}

Critical rules

The central rule: NEVER state an assertion as fact

Everything in a domain article is either:

• Something a human confirmed (green, validated)
• Something you believe with evidence (probability + source)
• Something you don't know (stated honestly)

There is no fourth category. "Here's how X works" stated flatly is the hallucination cascade trigger. Replace with "Here's what I believe about how X works, based on [source], with [confidence]."

The format rule: optimize for human consumption

The agent's research process (noticing, sensing, wondering) does NOT appear in the output. The output leads with intent, shows the map, links to lifecycle folders. Clean, scannable, human-readable.

But the agent must DO that thinking work internally before writing. Skip it and the output will be full of confident-sounding wrong assertions.

The folder rule: the folder IS the status

Don't put status in frontmatter and also in a folder. The folder is the single source of truth for lifecycle state. Moving a file between folders is how status changes.

The linking rule: link everything related

Every domain article should link to:

• Related plans, wherever the project keeps them
• Related seed/idea docs, if the project keeps them
• Related measurements (how we know if this domain is working)
• Related correction patterns (what agents have gotten wrong here)
• Any intent database entries, if the project keeps one
• Other domain INDEX.md files that touch this domain

The research rule: use sub-agents for heavy research

If sub-agent dispatch is available to you, use it. A domain article should synthesize knowledge from multiple sources — not just what you already know. Dispatch research sub-agents to:

• Search any configured institutional-memory tool for the domain's intent, patterns, corrections
• Read relevant past-session summaries or compactions, if the project keeps them
• Read relevant meta-analysis docs, if any exist
• Read the actual code files to verify claims
• Search any intent database the project keeps for related entries

The measurement rule: find how we measure it

For every domain, answer: how do we know if this domain is serving its intent? What metrics, KPIs, experiments, or dashboards exist? If none exist, that's a gap worth noting. Link to the measurement infrastructure in the article.

Quality check before finishing

Before declaring an article done, verify:

1. Does the INDEX.md lead with intent? Not "what exists" — what we're trying to accomplish.
2. Is every claim backed by evidence with a source? No flat assertions.
3. Are lifecycle folders populated correctly? Validated things in validated/, experiments in experiments/, etc.
4. Are related materials linked? Plans, seeds, measurements, corrections, intent entries.
5. Would a human scanning this immediately understand the domain's purpose? If they need to read code to understand what the article is about, it's not human-readable enough.
6. Would an agent consuming this know what's safe to build on and what isn't? The lifecycle folders should make this obvious.
7. Is there a "how to audit" section? So agents know how to check reality against intent.