Dok

Markdown was designed in 2004 to convert simple text to HTML for blog posts. That's it. Everything else it does is borrowed clothing that never quite fits.

Dok is a minimally structured document format designed for one purpose: pairing human thought with AI systems.

Files use the .dok extension.

A .dok file is plain text with ALL-CAPS section headers and two-space indented content. That is the whole format. There is no renderer, no plugin, no toolchain, and nothing to install.

SITUATION

  Login failures for all EU users since roughly 09:00 UTC.
  North America unaffected.

IMPACT

  ~4,200 users cannot authenticate. SLA breach threshold at 10:30 UTC.

KNOWN

  Edge config change deployed 07:45 UTC.
  TLS handshake failures logged at the edge node.
  Rollback attempted 10:15 UTC - no improvement.

UNKNOWN

  Whether the rollback propagated globally.
  Whether a second change shipped alongside it.

GOAL

  All EU users authenticate. Root cause identified and documented.

Paste that into any AI assistant and you get a materially better answer than you get from the same facts written as prose. That is the entire claim the format makes.

---

What problem it solves

Most documents fail before a word of prose is judged: the problem was never framed clearly enough for anyone — human or machine — to act on correctly. A troubleshooting cycle built on a badly stated problem is flawed from the first minute. The wrong people engage. The wrong things get fixed. The same issue returns.

The failure hits AI work harder, because a model will not push back on a vague brief. It will answer it. Confidently. At length.

Dok fixes this at the point of writing rather than at the point of reading. The section headers are a checklist you cannot skip silently: if you have no UNKNOWN section, that absence is visible on the page.

Why it works on AI systems specifically

Every section maps onto something a model needs and usually has to infer:

Section	What it does for the model
SITUATION	Primes context. Makes the document about something.
IMPACT	Signals priority and how much rigour the answer warrants.
GOAL	Defines what a good response looks like, so it can be checked.
GIVEN	Fixes constraints and assumptions so they are not re-litigated.
KNOWN	Removes established ground from the search space.
UNKNOWN	Points reasoning at the actual gap instead of the whole problem.
THEREFORE	Conclusions that follow from the above.
BECAUSE	The reasoning behind THEREFORE, when it is not obvious.
OPEN	Questions deliberately left unresolved.
PRINCIPLES	Values that govern decisions when the document steers behaviour over time.
EXAMPLES	Concrete illustrations.

UNKNOWN is the section that earns the format. It is the one every other document convention lets you omit, and omitting it is how documents mislead — including the ones you write for yourself. A .dok file with an honest UNKNOWN section tells an agent exactly where to spend its effort.

Getting started

1. Create a file ending in .dok.
2. Write SITUATION on a line by itself, leave a blank line, and indent your content two spaces.
3. Add sections from the vocabulary above as you need them. You do not need all of them.
4. Stop when the document is honest, not when it is complete.

A .dok file containing only a SITUATION section is valid. A diary entry is a valid Dok document.

There is nothing to install and no validator you must satisfy. If you can write plain text you can write Dok — and if a section is unclear, the document is incomplete. Clarity here is correctness, not style.

---

Named at Chiricahua National Monument, May 24, 2026.
The spires there took 27 million years of pressure and constraint to form.
No excess. Nothing forced. Just what remained after everything unnecessary was stripped away.

---

Why "Dok"?

The name comes from the middle of Su-dok-u — by way of a typo. The project was almost called "Sudoko" (classic misspelling), and somewhere in there the dok got extracted and promoted to the whole name.

The connection turned out to be more than phonetic. A .dok file works the way you solve a Sudoku: you start from the GIVEN (the fixed clues), track what you've deduced as KNOWN, stay honest about the UNKNOWN (the empty cells), and let THEREFORE fall out by constraint propagation. You don't guess — you eliminate until a value is forced.

Which is also what the spires were about. Sudoku is constraint propagation; the rock is 27 million years of constraint. The origin and the meaning ended up rhyming.

---

What's in this repo

File	What it is
SPEC.dok	The specification. Written in the format itself.
ADOPTING.dok	Three on-ramps for putting Dok into an existing workflow, and when not to.
PATTERNS.dok	Field guidance: document types, discipline rules, failure modes.
templates/	Blank skeletons with inline prompts. Copy, fill, delete the comments.
examples/	Complete worked examples you can copy.
harness/	Raw material for wiring Dok into an AI workflow. Conscience agent, CLAUDE.md block, linter spec.
PROJECT.dok	Build journal for the format and its tooling. Context, not guidance.

If you want to try it rather than read about it, go to ADOPTING.dok and do the first on-ramp. It takes ten minutes and needs no files.

Otherwise: this page, then PATTERNS.dok if you intend to use Dok for real work. SPEC.dok is the reference you consult, not the thing you read first.

Status

The format is stable and in daily use. The vocabulary is a small closed set and is defended as such — custom ALL CAPS sections are permitted, but every proposed addition to the standard set is treated as a cost.

Questions, disagreements, and reports of it not working are all welcome. The last of those is the most useful. The issue tracker is closed for now — see CONTRIBUTING.md for how to get in touch and what is worth sending.

License

Apache-2.0.