| Section | What it covers |
|---|---|
| Why | What breaks when the medium is wrong or documentation is missing |
| Documents, not code | Why .md and .yaml, not Python |
| Everything documented | Why undocumented things are invisible |
| Conciseness | Why verbose documentation is unread documentation |
#Why
HAAK is built for bounded reasoners — humans and AI agents with limited working memory navigating a growing store of knowledge. The medium matters: a system in Python is opaque to an agent that reads .md files. A system with undocumented components has invisible components. A system with verbose documentation has unread documentation. Each failure mode has the same consequence: the agent can't find what it needs, and the O(log N) advantage of hierarchical indexing collapses.
#Documents, not code
HAAK is a document system. The canonical medium is .md (content, methods, architecture, indices) and .yaml (frontmatter, state files, configuration). Not Python, not shell scripts, not databases.
Why this matters: agents navigate HAAK by reading index files, following links, and reading documents. Code is opaque to this navigation — an agent reading index.md can follow a link to 08-encapsulation.md but cannot follow a link to process_documents.py and understand what it does without executing it or parsing its AST. Documents are self-describing to any reader; code requires an interpreter.
Exceptions exist: a few skills bundle minimal shell scripts where unavoidable (PDF generation via pandoc, image conversion via sips). These are execution-only — the knowledge about what they do and why lives in .md documents (SKILL.md, architecture docs), not in the scripts themselves. The script is a narrow bridge; the documentation is the field.
#Everything documented
If it exists and isn't documented, it's invisible. An undocumented skill can't be discovered through index navigation. An undocumented architecture decision can't constrain future design. An undocumented method can't be composed by other methods.
Universal indexing is the structural implementation: every directory has index.md, every content file has description: in frontmatter, every method has a doc in patterns/methods/. The sweep method checks for gaps. But the architectural commitment is deeper than any specific check — it's the claim that HAAK's knowledge exists only insofar as it's written down. Nothing is "understood" or "obvious" or "everyone knows." If it's not in a file, it's not in the system.
#Conciseness
Documentation that nobody reads is functionally identical to no documentation. Verbose documentation costs twice: once to write (tokens, time), once to scan past (every agent reading an index pays for every token in it). The encapsulation argument applies: non-essential tokens in a navigation path degrade retrieval efficiency.
Rules:
- Methods explain why before how, but both sections are tight
- Index entries: one line in Contents, one paragraph in Details
- Architecture docs: section map at top, each section earns its place
- 500-line ceiling on any single file (from CLAUDE.md)
- Comments only for non-obvious why, never what
The test: after writing, ask "what can I delete?" If removing a sentence doesn't lose information, the sentence was padding.
Architecture 17 — Documentation Commitment — 2026 — Zachary F. Mainen / HAAK