write-docs

name	write-docs
description	Review and edit documentation, READMEs, guides, or technical prose. Use when writing, reviewing, or improving docs.
argument-hint	[file path or paste content]
disable-model-invocation	true

Writing Documentation

Read the full document first. Note purpose, audience, structure, and whether links or citations are present.

Review

Launch both agents concurrently. Pass each the full document content.

Agent 1: Prose & Structure Review

Apply these principles:

Prose:

• State each fact once. If a phrase implies something, don't state the implication separately.
• Cut, then cut again. If removing a sentence loses nothing, remove it.
• Prefer plain framing over jargon. "No config changes needed" over "existing parametric configuration is preserved."
• Acronyms earn their expansion. Expand on first use only when the words help the reader. "URL" and "HTTP" don't need expansion; "MTU (maximum transmission unit)" might.
• Define before use. Don't reference a term in section N that section N+1 will explain. Reorder, or fold the definition forward.
• Use active voice. "Draft 5 clarifies the spec" not "The spec is clarified by Draft 5."
• Be concrete. "Adds three keywords" not "includes several new features."
• Examples must break the obvious wrong assumption. If the naive approach handles the example, it's filler. "Hello, world" doesn't demonstrate i18n; "こんにちは" does.
• Omit filler. "To migrate" not "In order to migrate, you will need to."
• Keep modifiers close. "Can access only owned files" not "can only access owned files."
• Use parallel structure. List items and headings follow the same grammatical pattern.
• Intros must not restate the heading. Start with the first fact. Under "Webhooks", "Listen to events on your account..." beats "A webhook is a notification...".

Structure:

• Lead with the point. Essential information first. Readers skim.
• Open with what + who. First sentence names the artifact and its audience so readers self-select in one line. "This guide configures OAuth for backend services" beats "Authentication matters." End with a terse outcome clause, not a sentence.
• Progress from simple to complex. Common cases first, edge cases later.
• Headings enable skipping. Readers find what they need without reading everything before it.
• Headings need context. A bare term (id → $id) doesn't orient readers. Add the domain (Schema Identification: id → $id). Words before code.
• Tables beat repetition. When comparing items across the same dimensions, use a table.
• Bullets for lists, prose for flow. Bullets suit independent items. Sentences suit connected ideas.
• Include surrounding structure. Readers need enough context to understand where something belongs.
• Multiple cases prevent confusion. If one case might mislead about scope, add another.

Formatting:

• Restrain markup. Overused bold loses impact. Reserve it for defined terms.
• Prefer plain symbols. Use ✓ and ✗ over emoji.
• Reference-style links. Place link definitions immediately after their section, not at the document bottom.
• Consistent terminology. One term per concept throughout.

Agent 2: Link & Citation Review

Skip this agent if the document contains no links or citations.

Fetch every link. Verify at test time; do not assume URLs work.

• Check that the page loads (not 404, 403, ECONNREFUSED)
• Check that anchors resolve to the claimed section
• Check that the content matches the citation's claim

For broken links, find the canonical or closest equivalent. Prefer, in order:

1. The same resource at a new URL (moved, not removed)
2. A primary source covering the same claim (RFC, CVE, original paper)
3. A widely-maintained secondary source (OWASP, PayloadsAllTheThings)

Include citation text in link titles so context survives URL rot: [label]: https://example.com "Author, 'Title' (Year)"

Review information value — every link should teach the reader something the prose does not:

• Drop or replace links to generic pages that teach nothing about the cited concept.
• Keep spec links (RFCs, CWEs) when implementers need exact wording.
• Verify the claim matches the source. A CVE about X cited for a claim about Y is misleading. Find a source for the actual claim, or rewrite the prose.
• Citations as filler: "This is well-documented [link]" adds nothing — either the prose explains it or the citation does. Pick one.
• Claims need specifics. "Has been used in real-world attacks" is vague. Name the incident, CVE, or technique, or drop the claim.

Fix Issues

Aggregate findings from both agents. Fix each issue; skip false positives.

Summarize what was fixed, or confirm the document was clean.