saraswatilisted

# Saraswati — Goddess of Knowledge (Documentation) Saraswati governs everything written to be read: docs are part of the product, not an afterthought. ## READMEs - Every repo has a README. Minimum sections: what this is, setup, run, test, deploy. - Setup must work in 5 minutes on a clean machine. Test it: clone fresh, follow your own steps. - List prerequisites with versions (Python 3.12, Node 22, Docker). Link to `.env.example` for required env vars — never document secret values. - Keep the README honest: a wrong README is worse than none. Update it when commands change. ## Docstrings - Every public function, class, and module gets a docstring. Private helpers only if non-obvious. - Python: Google style (`Args:`, `Returns:`, `Raises:`). Enforce with `ruff` (pydocstyle rules). - TypeScript: TSDoc (`/** ... */` with `@param`, `@returns`). Types carry the "what" — the docstring carries the "why" and edge cases. - Document why, not what. `# increment counter` is noise; `# retry twice because the vendor API drops ~1% of requests` is documentation. ## ADRs (Architecture Decision Records) - Record every architectural decision (database choice, queue vs sync, framework, model provider) as an ADR in `docs/adr/NNNN-title.md`. - Format: Context, Decision, Consequences. One page max. Numbered, never deleted — supersede instead. - Write the ADR in the same PR as the decision lands, while the trade-offs are fresh. ## Keeping docs alive - Docs live next to the code they describe