outline · diff
git:20261010.3ba1fbe to git:20261113.8af5195
37 added, 15 removed. Audit A to A.
What this update changes in the checks
No check changed: every fixed check gives the same answer before and after this update.
A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.
---
name: outline
description: >-
Use this when turning a seed, interview, or set of facts into a writing plan
before drafting an article.
---
# Outline
- Turn a seed, interview, or signed facts into a writing plan. Do not write the article yet.
+ Turn raw material (a seed idea, interview notes, a pile of facts) into a plan the writer can approve. No prose yet.
- ## Arc
+ ## Start with one sentence
- 1. **Opening hook** — 2–3 specific options from lived detail, not “open with an anecdote.”
- 2. **Problem / question** — the tension. Why the reader should care.
- 3. **Mechanism** — the system or pattern that explains it.
- 4. **Evidence** — named facts, files, measurements. Flag gaps.
- 5. **Implications** — what the reader can actually do.
- 6. **Close** — how to return to the opening. No fake-profound kicker.
+ Write the claim the piece makes and the one thing a reader will learn. If you cannot, ask the writer the question that would unlock it. Everything below serves that sentence.
- ## Rules
+ ## Pick a shape
- - Teach test: name the one thing the reader will learn.
- - Vary section length. Do not make every block the same shape.
- - Present the outline for sign-off before drafting.
- - Invent nothing. If a number, quote, or source is missing, mark the gap.
- - After the outline is signed, draft section by section. Then run source-check, then No AI slop.
+ Choose the shape that fits the material, and say why:
- Source: adapted from [Nadiem Mahmoud, outline](https://github.com/nadiem99/claude-writing-skills/blob/5b52111e1bd30e93643929f17155e82aa26f771f/skills/pipeline/outline/SKILL.md). MIT; see [third-party notices](../../../THIRD_PARTY_NOTICES.md).
+ - **Story to mechanism.** A specific moment, the tension it shows, what explains it, the evidence, what the reader can do, a return to the moment. Good default for essays and X Articles.
+ - **Answer first.** The conclusion, then the reasons in order of weight, then caveats. Good for busy readers, docs, and decisions.
+ - **Teardown.** A thing, its parts one at a time, the verdict. Good for product or launch analysis.
+ - **Changed my mind.** What I believed, what I saw, what I believe now.
+
+ Don't force every section into the same pattern. Give heavy sections more beats and light ones fewer.
+
+ ## The plan
+
+ For each section: a working heading, the job it does in one line, the facts or examples it will use, and its rough length.
+
+ Also include:
+
+ - **Two or three openings,** each built from something real in the material (a moment, a number, a quote), not "start with an anecdote".
+ - **Gaps.** Every missing number, quote, source, or experience, marked `[GAP: ...]`. Never fill one by guessing.
+ - **Cut list.** Material that is true but off the point. Park it so the writer can see it was not lost.
+
+ ## Hand-off
+
+ Present the plan and wait for a yes. Expect the plan to move once drafting starts; a lot of the thinking happens in the draft. After sign-off the chain is draft, source-check, no-ai-slop.
+
+ ## Inspired by
+
+ - [Nadiem Mahmoud, outline](https://github.com/nadiem99/claude-writing-skills/blob/5b52111e1bd30e93643929f17155e82aa26f771f/skills/pipeline/outline/SKILL.md) (MIT). Does well: concrete hook options, a teach test, varied section shapes, and approval before drafting. Missing: one narrative arc for every piece, and it depends on its vault folders and publication pillars.
+ - [Paul Graham, Writing, Briefly](https://www.paulgraham.com/writing44.html). Does well: warns that detailed outlines aren't always worth it and that most ideas arrive while writing. Missing: no planning method at all.
+ - [Google Technical Writing Two, Organizing large documents](https://developers.google.com/tech-writing/two/large-docs). Does well: introduce information where the reader needs it, state what the document does not cover, and check the finished draft against the outline. Missing: written for technical docs, with nothing on hooks, story, or evidence gaps.
+
+ ## What this version adds
+
+ - A one-sentence claim before any structure.
+ - Four named shapes to pick from, with a reason, instead of one arc (a habit from Dani's own post workflow, which rotates shapes).
+ - A cut list so off-point material is parked, not lost, and an explicit note that the plan will change during drafting.