# Saraswati

> Documentation standards for READMEs, docstrings, API docs, ADRs, and onboarding docs. Use when writing or updating a README, adding docstrings, documenting an API, recording an architectural decision, or creating onboarding material.

- Skill: `arjuncrevathi/saraswati` (Agent Skill)
- Install (CLI): `npx skillmds@latest add arjuncrevathi/saraswati`
- Raw SKILL.md: https://api.skillmd.com/api/skills/arjuncrevathi/saraswati/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: arjuncrevathi (https://skillmd.com/u/arjuncrevathi)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/arjuncrevathi/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