kenoxa/use-writing

Route writing tasks to correct artifact structure. Classify first, then write.

Artifact Types

| Artifact | Key structure | |----------|--------------| | Docs (public/internal) | Diataxis: one mode per section — tutorial, how-to, reference, or explanation. Never mix. | | Changelog / release notes | User-facing impact grouped by type (added, changed, fixed, removed) | | README | Purpose → quick start → usage → contributing; scannable, no walls of text | | Runbook | Trigger → steps → verification → rollback; executable by someone unfamiliar |

Docs Impact

Classify scope before writing:

• Customer-facing: user-visible behavior, API usage, config surfaces, deployment/runtime
• Internal: engineering workflow, architecture contracts, contributor guidance, runbooks
• Both: both audiences affected
• None: record explicit skip rationale

Workflow

1. Classify — artifact type and docs impact lane before writing.
2. Structure first — headings and sections matching artifact type, then fill.
3. Write concretely — for human-facing prose (including chat summaries, status reports, and questions written back to the user), follow references/prose-quality.md. Every how-to includes a runnable example; every reference section uses consistent field table.
4. Verify completeness — required sections exist for artifact type.

Changelog Rules

• Breaking changes: lead with **BREAKING:**, state what fails if users do nothing, provide migration steps.
• What's New: user-facing outcomes ("Now supports..."), not internal refactors.
• Deprecations: announce before removing, provide replacements and timelines.
• Fixes: user impact ("X now works"), skip internal noise.

Anti-Patterns

• Writing without classifying artifact type
• Mixing Diataxis modes in a single section (tutorial steps inside reference page)
• Changelog entries describing code changes instead of user impact