| Show HN: HADS – A convention for writing technical docs that AI reads efficiently https://github.com/catcam/hads AI models increasingly read documentation before humans do. But docs are written for humans — verbose, contextual, narrative. This creates token waste and increases hallucination risk, especially on smaller/local models. HADS is not a new format. It's a tagging convention on top of standard Markdown: [SPEC] — authoritative facts, terse, bullet/table/code
[NOTE] — human context, history, examples
[BUG] — verified failure + fix (symptom, cause, fix)
[?] — unverified/inferred, lower confidence
Every document starts with an AI manifest — a short paragraph that tells the model what to read and what to skip. This is the core idea: explicit instructions in the document itself, not in the prompt.A 7B local model with limited context window can read a HADS document and extract facts correctly because it doesn't have to reason about structure — the document tells it how. The repo includes:
- Full specification (SPEC.md)
- Three example documents (REST API, binary file format, config system)
- Python validator (exit codes for CI/CD)
- Claude skill (SKILL.md) for AI-assisted doc generation All MIT. Feedback welcome — especially from people running local models. |