docs-rewrite

Docs Rewrite Skill

When to apply

Use when actively improving an existing technical doc — RFC, ADR, README, CLAUDE.md, architecture doc, blog-style technical post. The workflow modifies the file in place; it's not a read-only audit. For audit-only, use docs-review directly.

Trigger keywords: rewrite docs · improve this doc · optimize doc · docs rewrite · refresh doc · improve docs.

Workflow (Audit → Research → Rewrite → Validate)

Phase 1 — Audit (read-only)

Call docs-review against the target file. Capture:

• The baseline score (e.g., 71/100)
• The top 10 issues by severity
• Specific problem locations (file:line)

Do not edit yet. Present the audit summary to the operator.

Phase 2 — Plan-mode gate (mandatory)

Before any file edits, present a section-by-section rewrite plan:

# Rewrite plan: <file>

Baseline: 71 / 100

§ Introduction (lines 1-25)
  - Issue: thesis is hedged (3 questions in first paragraph)
  - Plan: hoist the central claim to the first sentence; convert
    questions to declarative statements

§ Section 2 (lines 30-89)
  - Issue: 4 unsourced assertions (per blog-factcheck)
  - Plan: find Tier 1-3 sources for each, or remove

§ Section 3 (lines 95-150)
  - Issue: paragraphs > 150 words (lines 102, 134)
  - Plan: split each into 2-3 paragraphs of 40-80 words

§ Conclusion (lines 200-220)
  - Issue: doesn't restate the thesis
  - Plan: add a 60-word citation capsule that names what was
    demonstrated and what remains open

Proceed to Phase 3 — but the plan is the contract (#4463).

The old rule paused here for explicit operator approval. It no longer does: a rewrite is version-controlled and therefore reversible, and the plan above is a reviewable artifact whether or not someone reads it before the edit. Ship the rewrite and let the diff be the review surface.

Two things still bind, because they are the risk the gate was really protecting against:

• The rewrite must not change technical meaning. Restructuring, tightening and re-voicing are in scope; altering a claim, an API contract, a version number, or a stated limitation is not. If the rewrite requires a meaning change to work, stop and surface it — that is a content decision, not a prose one.
• The plan and the rewrite must match. Do not expand scope mid-edit. If Phase 3 wants to go beyond the plan, re-plan first.

Run an adversarial factual pass over the result (blog-factcheck or the docs rubric) before calling it done.

Phase 3 — Research (when claims need sources)

For any unsourced claim flagged by blog-factcheck:

1. Search for a Tier 1-3 source supporting the claim. Use the tier ladder in .rules/docs-rubric.md:
   • Tier 1: RFCs, language/runtime specs, official vendor docs, peer-reviewed papers
   • Tier 2: Established benchmarks (SWE-bench, HumanEval), NIST publications, named-engineer first-hand post-mortems
   • Tier 3: Quality engineering trade press (LWN, ACM Queue, USENIX), well-maintained open-source READMEs
2. If no Tier 1-3 source exists, either:
   • Remove the claim, OR
   • Reframe as [ORIGINAL DATA] / [PERSONAL EXPERIENCE] / [UNIQUE INSIGHT] (only when genuinely first-hand)
3. Wrap any fetched external content per .rules/untrusted-input.md fence convention before quoting.

Phase 4 — Rewrite (apply changes in declared order)

Apply changes in the exact order from the plan. Per the rubric, prefer these patterns:

• Answer-first H2s — every H2's opening paragraph (40-60 words) names what the section delivers and includes one concrete claim with evidence.
• Citation capsules — 40-60 word self-contained passages per section. Each is independently quotable; if you can't quote it alone, the section's structure is wrong.
• Info-gain markers — flag genuinely first-hand value with [ORIGINAL DATA] / [PERSONAL EXPERIENCE] / [UNIQUE INSIGHT]. Don't apply these to synthesis of public knowledge — they're reserved for what's not findable elsewhere.
• Paragraph + sentence discipline — paragraphs 40-80 words (hard ceiling 150); sentences 15-22 words; ≤ 25% over 25.
• H2 cadence — an H2 every 200-400 words.

Phase 5 — Validate (re-call docs-review)

Run docs-review again on the rewritten file. Compare:

• New score vs. baseline
• Top-10 issues vs. baseline issues (which were resolved?)
• Any newly-introduced issues (regressions)

Reject the rewrite if the new score is lower than the baseline. This is non-negotiable: if the rewrite made the doc worse by the rubric, revert and re-plan. The validate gate is the rubric's purpose.

Output:

# Rewrite complete: <file>

Score: 71 → 87 (+16) ✅

Issues resolved (from baseline top-10):
  - thesis is hedged → resolved (line 3)
  - 2 unsourced assertions → resolved (added Tier 1-2 citations)
  - § 3 paragraph > 150 words → resolved (split into 3)

Issues newly introduced: none.

Three new top issues (post-rewrite):
  1. [Medium] line 142 — H2 cadence: 480 words between §3.2 and §3.3
  2. [Low] line 88 — Year missing on Linux kernel cite
  3. [Low] line 219 — Conclusion could include one info-gain marker

What this skill does NOT do

• Re-implement scoring. Calls docs-review. Always.
• Skip the plan-mode gate. Even when the operator says "just rewrite it" — present the plan first; an operator who wants to skip can approve in one line.
• Greenfield doc creation. That's documentation-management's outline + write workflow. This skill improves existing docs.
• Multi-doc batch rewrites in one invocation. Handle one doc per invocation; batch is a separate workflow if it earns its keep.
• Edit code or comments. Code changes go through code-simplification or other code-focused skills.
• Override docs-review's reject. If validate says the score regressed, revert. Don't reason around it.

See also

• skills/docs-review — the read-only audit counterpart this skill calls
• .rules/docs-rubric.md — the canonical rubric
• .rules/untrusted-input.md — fence convention for any external content quoted into the doc
• skills/documentation-management — operating manual for doc work