/doc-generator

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
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

`leyline:document-conversion` and its `project-import` module)

• 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).

11. One Term per Concept, One Home per Fact

When a concept already has a name, use the term the repository already uses. A new synonym makes readers ask whether two things exist. When a number, threshold or path is stated in another file, link to the file that states it. A second copy drifts, and code left inconsistent with its docs is measurably more bug-prone (`docs/knowledge-corpus/decoherence.md`).

When a document replaces another, describe only the current state in the new one. The superseded document gets the forward pointer and its status: deleted, deprecated, or still valid for a named case. The commit message records the supersession.

Required Progress Items

1. `doc-generator:scope-defined` - Target files and type identified 2. `doc-generator:style-loaded` - Style profile applied (if available) 3. `doc-generator:content-drafted` - Initial content created 4. `doc-generator:slop-scanned` - AI markers checked 5. `doc-generator:quality-verified` - Principles checklist passed 6. `doc-generator:user-approved` - Final approval received

Mode: Generation

For new documentation:

Step 1: Define Scope

## Generation Request

**Type**: [README/Guide/API docs/Tutorial]
**Audience tier**: [newcomer | practitioner | expert | persona: <one line>]
**Audience**: [developers/users/admins]
**Audience size**: [1 / small team / org / public]
**Read frequency**: [once / weekly / per-invocation]
**Thesis**: [one sentence the reader must walk away with]
**Length target**: [~X words or sections]
**Style profile**: [profile name or "default"]

The **Thesis** field is required. If you cannot state the takeaway in one sentence, the scope is not ready. Audience size and read frequency feed the reader-time budget (see `scribe:slop-detector` module `document-economy.md`): a skill loaded daily by 50 users has a wildly different budget than a 1:1 design note.

**Audience tier** is required too, and when the request omits it, **ask, do not guess**. A guessed reader produces a document that reads as competent and serves nobody. The tier table, the Socratic set for eliciting one, and the creative-writing carve-out are in `scribe:slop-detector` module `audience-targeting.md`.

The tier decides what survives the draft:

| Tier | Keep | Move to a deep dive | |------|------|---------------------| | `newcomer` | The one path that works, end to end | Internals, history, alternatives considered | | `practitioner` | Repo-specific facts they cannot derive | General-domain teaching | | `expert` | The novel claim and its numbers | Nothing. Deep dives land here |

Step 2: Load Style (if available)

If a style profile exists:

cat .scribe/style-profile.yaml

Apply voice, vocabulary, and structural guidelines.

Step 3: Draft Content

**Lead with the thesis.** The first paragraph must state the single takeaway. If a reader stops after the lead, they should still leave with the message. Echo the thesis once in the body and once at the close. Cut every other repetition.

Follow the 10 core principles above. For each section:

1. Start with the essential information (state the thesis or a clear instance of it) 2. Add context only if it adds value (does it carry, instance, or bound the thesis?) 3. Use specific examples (one is proof; two is emphasis; three is filler) 4. Prefer prose over bullets 5. End when information is complete (no summary padding, no "in conclusion" restatements)

**Run the cu