HADS — A Simple Convention for Writing Docs That AI Can Actually Read

github.com/catcam/hads

AI models read your documentation before your users do. But documentation is written for humans.
This mismatch has a real cost: token waste, hallucinations, and local models that just give up on long docs.
I spent a few weeks debugging this while building a tool that generates Ableton Live project files from JSON. Every time I fed technical documentation to a model, the same thing happened — half the context window consumed by narrative prose, the model extracting facts incorrectly, or missing critical bug fixes entirely.
The fix wasn't a better prompt. It was better-structured docs.
Introducing HADS
HADS (Human-AI Document Standard) is a tagging convention for Markdown. Not a new format. Not a new tool. Just four tags that tell both humans and AI models what kind of content they're reading.
[SPEC] Authoritative fact. Terse. AI reads always.
[NOTE] Human context, history, examples. AI can skip.
[BUG] Verified failure + fix. Always read.
[?] Unverified / inferred. Lower confidence.
Every HADS document also starts with an AI manifest — a short paragraph that explicitly instructs the model what to read and what to skip.
markdown## AI READING INSTRUCTION

Read [SPEC] and [BUG] blocks for authoritative facts.
Read [NOTE] only if additional context is needed.
[?] blocks are unverified — treat with lower confidence.
That's it. The document teaches the model how to read it.
Why This Works for Small Models
A 7B local model with a 4k context window can't reason about document structure reliably. But it can follow explicit instructions at the top of a document.
The manifest removes the need for structural reasoning entirely. The model doesn't have to decide what's important — the document tells it.
What a HADS Document Looks Like
Here's a real example — authentication documentation:
markdown## Authentication

[SPEC]

• Method: Bearer token
• Header: Authorization: Bearer <token>
• Token lifetime: 3600 seconds
• Refresh: POST /auth/refresh

[NOTE]
Tokens were originally session-based (pre-v2.0). If you see legacy docs
mentioning cookie auth, ignore them — the switch happened in 2022.

[BUG] Token silently rejected after password change
Symptom: 401 with body {"error": "invalid_token"} — identical to expired token.
Cause: All tokens invalidated on password change, no distinct error code.
Fix: Re-authenticate on any 401. Do not assume 401 always means expiry.
An AI reading this extracts: method, header, expiry, refresh endpoint — in one [SPEC] block. A human reads the [NOTE] and understands history. Both read the [BUG].
No duplication. One document. Two readers.
The BUG Block Is the Most Important Innovation
Technical documentation's most valuable content is known failure modes. Someone hit a wall, debugged it, wrote it down. In normal docs this gets buried in a changelog or a Stack Overflow answer from 2019.
HADS makes [BUG] blocks first-class. Every AI reading a HADS document reads all [BUG] blocks before generating any code. This alone eliminates a class of hallucinations.
What's in the Repo

SPEC.md — full formal specification
examples/ — three complete example documents (REST API, binary file format, config system)
validator/validate.py — Python validator with CI/CD exit codes
claude-skill/SKILL.md — skill file for Claude to generate HADS docs automatically

All MIT. Zero dependencies to read a HADS document.
GitHub
github.com/catcam/hads
Feedback welcome — especially from people running local models. Does the manifest approach actually help with your context management?