devils.md

The devil is in the details.

A Detail Devil document is a single Markdown file that tracks a project's last-mile details — decisions and plain matters of fact alike, asked as questions — as a dependency graph. It exists to catch the thing ordinary documents hide: an answer that rests on something nobody has settled yet.

Home: https://devils.md · Specification: https://devils.md/spec/v0.1/ (latest at /spec/, source in SPEC.md)

The whole format is one rule

A question is resolved when it has an answer and every question it depends on is resolved.

Because that rule tests two facts, every question is in exactly one of four states:

	all dependencies resolved	some dependency unresolved
answered	Resolved	Provisional
unanswered	Ready	Blocked

Provisional is the devil — an answer standing on ground that is still open. Ready is the set of questions that can usefully be answered right now.

Neither is written in the file. Both are computed from it on every read, which is why a document cannot misreport its own progress.

What it looks like

# Can we launch v1.0 publicly?

## Which email provider?

Answer: Resend on port 2587 — DigitalOcean blocks 587.

Assumes [[who pays for infra?]] lands under $20/mo.

## Who pays for infra?

Need to ask before committing to a paid tier.

Who pays for infra? is Ready. Which email provider? is Provisional — answered, but on an open assumption. The root is Blocked. Nobody recorded any of that.

Four constructs

• A heading ending in ? is a question. Any other heading is an organizational section and carries no state.
• An Answer: paragraph, or an ### Answer section, is the answer. Everything else under a question is notes, so "blocked on the budget, need to ask Dan" never passes for a decision.
• Nesting is dependency. Write a plain outline and you have already written a graph.
• A [[reference]] is dependency too. It expresses the edges an outline cannot — between siblings, or to a question several things depend on. Name one that does not exist and you have declared it, open, without leaving your sentence.

Cycles are allowed and reported as a set to decide jointly, because the venue really does depend on the headcount and the headcount on the venue.

Details, not roadmaps

The format is deliberately low-level — the name is the scope. A question may be a decision (which email provider?) or an empirical fact (how many people are coming?); what the format tracks is not deliberation but open-ness. Roadmaps, milestones, and prioritization belong in other tools, and a broad question appears in a document only as the root that details hang from. This is for devil-in-the-details problems: the last mile, not the plan.

Start one

Add a DEVILS.md to your project root and open it with the standard preamble (§3.1), so anyone — or any agent — meeting the file cold knows how to read it:

> **What this file is.** The unsettled details of this project — decisions and
> plain matters of fact alike — tracked as questions, and what depends on what.
> A heading ending in `?` is a question; the block marked `Answer:` beneath
> it is its answer.
>
> **The part that isn't obvious.** A question also depends on every question
> nested beneath it, and on any question it names in `[[double brackets]]`. It
> counts as resolved only when it has an answer *and* everything it depends on is
> resolved too. So an answered question sitting on unanswered ones is an
> assumption, not a decision — making those visible is the point of the file.
>
> Format spec: https://devils.md

Then write questions. That is the entire onboarding.

Tooling

A reference implementation in dependency-free Ruby — one file, no gems.

bin/devils              # report on ./DEVILS.md
bin/devils path/to.md   # or any other document
rake test               # 31 tests

devils.md — 16 questions: 9 resolved, 2 provisional, 3 ready, 2 blocked

Provisional — answered on open ground (2)
  Is the format specified?
    rests on Do references in a plain section's block declare a question?
    rests on May a reference span a line break?

Ready — answerable now (3)
  Do references in a plain section's block declare a question? (unblocks 4)
  May a reference span a line break? (unblocks 4)
  How do people discover the format? (unblocks 1)

Devils::Document also exposes trace — the unresolved questions beneath any question, the answer to "why isn't this resolved?" — and leverage, the number of questions waiting on one, which ranks the Ready queue.

A second implementation in dependency-free JavaScript, written clean-room from the spec as a test of its precision, lives in js/:

node js/devils.mjs DEVILS.md       # report (--json for machine output)
node --test js/devils.test.mjs     # 31 tests

Status

v0.1. SPEC.md on main is the working draft of the next version and changes freely; released versions are frozen under /spec/ and never change (see RELEASING.md).

The specification has been through two full implementations. Writing the first surfaced and closed five underspecified cases; the second — a clean-room JavaScript port written from the spec alone, without reading the first — surfaced three more, of which two are still open decisions. Everything open is tracked in DEVILS.md, in its own format.

A user interface for the format is being built separately, on coordination.tools.

License

MIT. The specification is free to implement, with no permission required.