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.

Nice man, will try to implement to my newest project :)