| name | generate-docs |
| description | Generate or update docstrings, ADRs, README sections, cookbook recipes, or user guides following Katana's documentation standards. |
| allowed-tools | ["Read","Write","Edit","Grep","Glob","Bash(uv run poe format)","Bash(uv run poe docs-build)","Bash(ls docs/adr/*)"] |
/generate-docs — Generate Documentation
PURPOSE
Write or update docs (docstrings, ADRs, README, cookbook, guides) using project standards.
CRITICAL
- Only document the public surface — don't add docstrings or comments to code you didn't otherwise change.
- Code examples must be tested — never write usage examples that haven't actually run.
- ADRs are sequential — find the next number; never reuse.
STANDARD PATH
1. Pick the doc type
| Type | Goes In | When |
|---|
| Docstring (Google style) | inline | public functions/classes/modules |
| ADR | docs/adr/NNNN-*.md | architectural decision |
| README section | the relevant README.md | new package or major feature |
| Cookbook recipe | docs/COOKBOOK.md | new usage pattern |
| User guide | docs/*.md | complex feature needing step-by-step |
2. Docstrings (Google style)
def unwrap_as(response: Response, expected_type: type[T]) -> T:
"""Extract and validate a parsed response as the expected type.
Args:
response: The HTTP response to unwrap.
expected_type: The type to validate the parsed response against.
Returns:
The parsed response cast to the expected type.
Raises:
AuthenticationError: If 401.
ValidationError: If 422.
APIError: For other non-success status codes.
"""
3. ADRs
ls docs/adr/*.md | grep -o '[0-9]\{4\}' | sort -n | tail -1
Increment, copy docs/adr/template.md, fill in. Update docs/adr/README.md index.
4. Format
uv run poe format
88 char line length, ATX headers (#, not ===).
If updating MkDocs content:
uv run poe docs-build
EDGE CASES
- Existing doc is wrong — fix it as part of the work. Don't leave bad docs next to new ones.
- Adding cookbook recipe — every code block must be runnable; mention required imports and config.
RELATED
harness-kit:documentation-writer skill — generic progressive-disclosure doc style/review skill — flags missing or outdated docstringsCLAUDE.md "Detailed Documentation" — canonical project doc map
