| name | doc-generator |
| description | Generates or remediates documentation with human-quality writing. Use when creating new docs, rewriting AI-generated content, or applying style profiles. |
| globs | **/*.md |
| alwaysApply | false |
| category | artifact-generation |
| tags | ["documentation","writing","generation","remediation","polish"] |
| tools | [] |
| complexity | medium |
| model_hint | standard |
| estimated_tokens | 1600 |
| progressive_loading | true |
| modules | ["modules/generation-guidelines.md","modules/remediation-workflow.md","modules/quality-gates.md"] |
| dependencies | ["scribe:slop-detector"] |
Documentation Generator
A document costs the sum of its readers' time. Earn that
cost or cut.
Generate documents that are grounded in specific claims, lead
with their thesis, and earn every sentence. Filler phrases like
"In today's fast-paced world" and vague descriptors like
"thorough" or "complete" without evidence are bloat. So is
any sentence that does not carry, instance, bound, or repeat
the document's one takeaway.
This skill enforces both sentence-level cleanliness (no
slop vocabulary, em dash overuse, or sycophantic openers) and
document-level economy (thesis-first, every sentence
earns weight, repetition reserved for the thesis). See
Skill(scribe:slop-detector) module document-economy.md
for the full rubric.
When NOT To Use
- Converting an external file into markdown (use
scribe:doc-importer)
- Scanning existing prose for AI patterns (use
scribe:slop-detector)
Core Writing Principles
Use active voice and an authorial perspective. Explain the
reasoning behind technical choices (why this database, not
that one) rather than presenting neutral boilerplate. Use
bullets sparingly for short, parallel summaries. Convert
multi-line bullet waterfalls into prose so the reasoning
survives.
Vocabulary and Style
Avoid business jargon and linguistic tics like mirrored
sentence structures or em dash overuse. Use the imperative
mood for docstrings ("Validate input", not "Validates").
Do not humanize non-living constructs ("the code wants",
"the function speaks to").
| Instead of | Use |
|---|
| fallback | default, secondary |
| leverage | use |
| utilize | use |
| facilitate | help, enable |
| comprehensive | thorough, complete |
9. Limit Humanizing Constructs
"Lives under," "speaks to," and similar phrases only make sense
for living things.
10. Imperative Mood for Docstrings
"Validate" not "Validates" (per PEP 257, pydocstyle, ruff).
Required TodoWrite Items
doc-generator:scope-defined - Target files and type identifieddoc-generator:style-loaded - Style profile applied (if available)doc-generator:content-drafted - Initial content created
