ha:document
Generate module-level and function-level PEP 257 docstrings for Home Assistant integration modules, and TSDoc for ha-frontend Lit components. Use when explicitly asked to write docstring/TSDoc comment
SKILL.mdskills/document/SKILL.md
GitHubDocument
Generate documentation for newly implemented features.
Usage
/ha:document .claude/plans/magic-link-auth/plan.md
/ha:document magic link authentication
/ha:document # Auto-detect from recent plan
Iron Laws
- Never remove existing documentation — Existing docs may reflect design intent that isn't obvious from code alone; update rather than replace
- PEP 257 docstring on every module, class, and function — ruff's
Drules enforce this in core; the header is a single imperative sentence ending in a period (PS20 — "Please follow PEP8 for docstrings." — MartinHjelmare, https://github.com/home-assistant/core/pull/156401#discussion_r2746284568) - ADRs capture the "why", not the "what" — Code shows what was built; ADRs explain why this approach was chosen over alternatives
- Match the docstring to the function's public API — Document parameters, return values, and raised exceptions (
ConfigEntryNotReady,ServiceValidationError, ...); callers shouldn't need to read the implementation - DO NOT write rich documentation for untested code — a lint-satisfying single-sentence docstring is fine, but detailed Args/Raises documentation implies a stable contract; document only after tests confirm the function behaves as described
What Gets Documented
| Output | Description |
|---|---|
| Module docstring | For new integration modules/classes missing documentation |
| Function/method docstring | For public functions/methods without docs (TSDoc for frontend Lit components) |
| README section | For user-facing features |
| ADR | For significant architectural decisions |
Workflow
Step 0: Pre-check (avoid no-op runs)
Run git diff --name-only HEAD~5 | grep -E '\.(py|ts)$' | grep -v '^tests/' | head -20 to check for new .py (integration) or frontend .ts files.
If NO new files were added (only modifications), skip the full audit and report: "No new modules — documentation coverage unchanged." This prevents 35-message analysis sessions that conclude "PASS" with zero output (confirmed: session bb0a0454 wasted ~2K tokens on no-op).
- Identify new modules from recent commits or plan file
- Check documentation coverage (module docstrings, function docstrings, TSDoc on Lit components)
- Generate missing docs using templates
- Add README section if user-facing feature
- Create ADR if architectural decision was made
- Write report to
.claude/plans/{slug}/reviews/{feature}-docs.md
When to Generate ADRs
| Trigger | Create ADR |
|---|---|
| New PyPI requirement in manifest | Yes |
| New config-entry version bump / migration | Maybe (if migration non-obvious) |
| New coordinator scheduling pattern or stateful in-loop cache | Yes (explain why polling/push/cache is needed) |
| New integration module split | Maybe (if boundaries non-obvious) |
| New auth mechanism (OAuth, reauth flow) | Yes |
| Performance optimization | Yes |
Integration with Workflow
/ha:plan → /ha:work → /ha:review
↓
/ha:document ← YOU ARE HERE (optional, suggested after review passes)
References
${CLAUDE_SKILL_DIR}/references/doc-templates.md— Module docstring, function docstring, README, ADR templates${CLAUDE_SKILL_DIR}/references/output-format.md— Documentation report format${CLAUDE_SKILL_DIR}/references/doc-best-practices.md— PEP 257 and TSDoc documentation best practices${CLAUDE_SKILL_DIR}/references/documentation-patterns.md— Detailed documentation patterns