generate-docs

name	generate-docs
description	Generate documentation. Public APIs must have JSDoc. No vague docs.

/generate-docs [path]

Generate documentation. Public APIs MUST be documented.

No arguments? Describe this skill and stop. Do not execute.

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.