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.