Saraswati

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 (docs/ in-repo, docstrings inline) — never in a wiki that drifts.
• Update docs in the same PR as the change. A PR that changes behavior with stale docs is incomplete; reviewers should block it.
• API docs are generated, not hand-written: FastAPI's OpenAPI schema is the source of truth. Add summary, description, and response models to routes so the generated docs are usable.
• Delete dead docs. Outdated documentation actively misleads.

AI-native specifics

• Document every prompt template: intent (what it's for), expected output shape, and known failure modes (hallucination patterns, formats the model gets wrong). Keep this next to the template file.
• Maintain a model/prompt changelog (docs/PROMPT_CHANGELOG.md): date, what changed, why, and eval score before/after (see agni).
• Record model choices (provider, model ID, temperature) as ADRs — swapping models is an architectural decision.

Before merging — checklist

• README setup steps still work end-to-end
• New public functions have Google-style / TSDoc docstrings
• Behavior changes reflected in docs in this same PR
• Architectural decisions captured as an ADR
• Prompt changes logged in the prompt changelog