/generate-docs [path]

Generate documentation. Public APIs MUST be documented.

First: Activate Workflow

mkdir -p .claude && echo '{"skill":"doc-code","started":"'$(date -Iseconds)'"}' > .claude/active-workflow.json

Craft Standards (MANDATORY)

Write documentation a master craftsperson would be proud of.

Documentation must look like it was written by a skilled human technical writer, not generated by AI.

AI Antipatterns in Documentation to REJECT

• •Restating the obvious (@param name - the name)
• •Verbose descriptions that add no information
• •Generic placeholder text ("This function handles...")
• •Documenting every private/internal detail
• •Comments that describe WHAT instead of WHY
• •Changelog-style comments in code

Human Craft in Documentation

• •Document the WHY, not the obvious WHAT
• •Clear examples that show real usage
• •Concise descriptions that respect the reader's time
• •JSDoc that adds value beyond the type signature
• •README sections that help users get started fast

Test: Would someone learn something from this doc they couldn't infer from the code? If not, cut it.

⚠️ STRICT REQUIREMENTS - NO JUDGMENT CALLS

You MUST do these documentation tasks. Not "consider" - DO:

1. •PUBLIC FUNCTIONS - Add JSDoc/TSDoc to EVERY exported function
2. •COMPLEX LOGIC - Add inline comments for non-obvious code
3. •README - Update if feature adds new usage/commands
4. •TYPES - Document non-obvious type fields

FORBIDDEN (Phase will FAIL if detected):

• •Over-documenting obvious code
• •Adding comments that just repeat the code
• •Saying "documentation would help" without writing it
• •Skipping JSDoc on public APIs
• •Writing vague descriptions ("handles the thing")

Process

1. •Analyze - Identify what needs documentation
2. •Document - Add JSDoc to public APIs, inline comments where needed
3. •Update README - If feature affects usage
4. •Report - List what was documented

REQUIRED Output Format

## Documentation: [target]

DOCUMENTED:
- src/service.ts: 5 functions with JSDoc
- src/types.ts: 3 types with field comments
- README.md: Added "Usage" section for new feature

PUBLIC_APIS_DOCUMENTED: N
README_UPDATED: yes/no
COMMENTS_ADDED: N

APPLIED:
- [expert]: [decision]

DOC_COMPLETE

Validation (Phase will FAIL if violated)

• •No DOCUMENTED section
• •PUBLIC_APIS_DOCUMENTED: 0 when public functions exist

🛑 MANDATORY STOP

After documenting:

• •DO NOT proceed to any other workflow step
• •DO NOT make additional code changes

Your turn ends here. Output DOC_COMPLETE and STOP.