Output Engineering: Let AI Follow a Checklist When Generating Long-Form Content
Cross-validated by three perspectives: writing theories (Zinsser's On Writing Well / Heath's Made to Stick / Rosenfeld's Information Architecture), learning sciences (Sweller's CLT / Brown's Make It Stick / Wiggins' backward design), and documentation practices of top tech companies (Stripe / GitLab / Linear / Anthropic / Google SRE).
Meta Principles (Post at the top, recite before starting each time)
- If you don't gain new insights after reading it yourself, neither will the readers. Writing is thinking on paper, not filling in templates.
- The goal is "readers can use it next time", not "readers can understand it this time". Backward design: First figure out what "reusable tool" readers will have in hand after reading (a comparison table / a judgment framework / a decision path / a mnemonic), then work backward to decide what to write.
- Don't list menus — give recommendations + one-sentence reasons. AI likes to "list 5 options for you to choose", but good documentation is opinionated.
Trigger Conditions
Trigger (needs medium-to-long HTML content for human reading):
- "Do a retrospective / summary / compilation / organization"
- "Create a tutorial / study guide / getting-started document"
- "Explain X clearly / organize into readable HTML"
- "Create a report / explanation document"
- Any request for structured reading content of over 500 words
No Trigger (short output / operational / non-HTML requirements):
- Writing code / fixing bugs / modifying files
- Answering in one or two sentences
- Code diffs / short lists
- User explicitly requests "answer in markdown" / "respond directly in chat"
- PRDs (use prd-doc-writer) / article writing (use writing-assistant) / naming (use product-naming)
Important: This skill only produces HTML format. Do not use this skill if the user requests markdown.
Operation Mode
Trigger
↓
Stage 1: Mandatory use of AskUserQuestion to ask 4 key questions in one go
↓
User completes selection
↓
Stages 2-6 run internally in AI (no verbal explanation to user)
↓
Generate HTML, add a "Current Configuration" confirmation bar at the top, and automatically open in browser
Exceptions (skip Stage 1 questions):
- The user has clearly specified all 4 parameters in the prompt (e.g., "5,000-word retrospective for PMs, narrative style")
- The user explicitly says "do it quickly" / "just give me one" / "don't ask"
Stage 1 (Mandatory): Use AskUserQuestion to Ask 4 Questions in One Go
Must use the AskUserQuestion tool to initiate a single inquiry containing the following 4 questions. The question wording and options can be adjusted slightly, but the dimensions cannot be changed.
Question 1: Who is it for? (Audience)
| Option | Description |
|---|
| PM / Product Manager | Focuses on stories, benchmarks, decisions, and reusable frameworks |
| Engineer / Technical Newcomer | Includes code snippets, technical decisions, and hands-on guides |
| Executive / Decision-Maker | TL;DR + data + investment/rejection recommendations |
| Self / Memorandum | Timeline + note-taking style, for future reference |
| External User / Customer | Tutorial-style, builds conceptual step-by-step |
Question 2: What will readers gain after reading? (Goal)
| Option | Description |
|---|
| Decision Basis | Can decide go/no/hold after reading |
| Operation Steps | Can take action after reading |
| Conceptual Understanding | Knows what it is after reading |
| Emotional Resonance | Feels touched after reading |
| Memorandum Archiving | Can refer to it later after reading |
Question 3: How detailed should it be?
Design Reason: Word count is a post-experience feeling and often cannot be fulfilled (forcing to meet word count will lead to fluff when materials are insufficient). Therefore, word count is not shown to users, only two perceptible commitments are made — "What it includes" and "Reading time".
| Option | What it includes | Reading Time |
|---|
| Quick Read Card | TL;DR + 1 core framework / 1 main diagram, shareable | 3 minutes |
| Standard Version (default recommendation) | Core points + stories + counterexamples + exit | 5-8 minutes |
| Teaching Version | + Background extension + multi-perspective comparison + reusable framework + boundary declaration | 20-30 minutes |
| AI Selection | Derived from "audience tolerance time × number of independent information points in materials" | — |
How to determine word count (internal reference for AI, not told to users, not included in the configuration bar):
- Reading speed is calculated based on PM/product content: 300 Chinese characters per minute.
- Quick Read Card → internal target ~800 words | Standard Version → ~1,500-2,500 words | Teaching Version → ~5,000-8,000 words
- The real stopping criterion is "whether each item in the 'What it includes' list is fully covered" (the four elements of standard version: core points / stories / counterexamples / exit are all complete; teaching version adds 4 extended items), not "word count is reached".
Stage 1.5 (Mandatory): Material Volume Self-Check + Active Persuasion
After answering Question 4 and before entering Stage 2, AI must perform a self-check. There is only one scenario that triggers persuasion:
- Single-document materials (single README / single PRD / single article) with original text < 3,000 words + user selects "Teaching Version"
When triggered, AI must interrupt the process and actively persuade the user:
⚠️ Reminder: You selected the Teaching Version (20-30 minutes of reading), but the material is a single [README/PRD/article] with only X words. Forcing to expand to the Teaching Version depth will result in approximately 60% of the content being AI-derived (background extension / comparison / framework), not from the original material. Please choose one of the following:
① Switch to "Standard Version" (5-8 minutes), which just covers the existing depth of the material
② Supplement 2-3 similar materials (multiple PRDs / multiple articles in the same field / all project documents), so the Teaching Version has a proper foundation
Do you want to continue with the Teaching Version? (Continue / Switch to Standard Version / I'll supplement materials)
- User switches version: Proceed to Stages 2-6 with the new version
- User supplements materials: Wait for the user to complete supplementing before continuing
- User insists on Teaching Version: Generate the output, and must add a "Material Volume Warning" banner + label each derived section with "Derived" (see output rules)
Multi-source materials / Non-Teaching Version → No persuasion triggered, directly enter Stage 2.
Question 4: Style + Focus (Combined)
Each option is a combination of "visual tone + content focus":
| Option | Visual Style | Content Focus |
|---|
| Engineering Serious | Fresh blue (Stripe/Linear style) | Focuses on lessons and methodologies |
| Narrative Reading | Warm bookish tone (off-white + dark brown) | Focuses on story completeness |
| Concise Decision-Making | Minimalist black and white (Apple documentation style) | Focuses on data impact |
| Technical Depth | Dark tech style (GitHub Dark) | Includes code details |
| AI Selection | — | Recommended by default based on audience |
After user selection, write the 4 parameters into the "Current Configuration" section at the top of the HTML (see "Output File Rules" below).
Stages 2-6 (Run internally in AI, no verbal explanation to user)
Stage 2 · Define the Goal (Backward Design)
Based on the user's selection of "What will readers gain after reading" in Stage 1, further specify: What "reusable item" will readers have in hand after reading?
- A comparison table (how to choose between A and B)
- A judgment framework (when to do X)
- A decision path (when encountering Y → first a → then b)
- A mnemonic (short, easy to remember)
- A checklist
Anti-Pattern: Only defining the goal as "readers understand".
Stage 3 · Capture Core Points (≤ 3)
Working Memory Iron Law (Sweller's Cognitive Load Theory): New readers can only process 3-4 new chunks at a time. Default to 3, maximum 5; if exceeding, must merge or demote to appendix.
The relationship between core points must be explicitly clarified:
- [Parallel] 3 independent points, can be read in any order
- [Dependency Chain Why → What → How] Must be in order
Half-Cut Test: After listing all candidate points, ask "Which ones would you keep if you could only keep half" — the remaining ones are the real backbone.
Stage 4 · Choose Main Structure (One, No Overlapping)
Warning: This stage is most prone to "demonstrating cognitive overload yourself" — give recommendations + one-sentence reasons, do not list menus.
One main structure (selected based on content nature):
| Content Nature | Recommended Structure |
|---|
| A process / multi-step decision | Timeline |
| Multiple parallel topics | Categorized chapters |
| Solving a specific problem | Problem-oriented Q&A |
| Teaching / conceptual step-by-step | Gradual teaching from shallow to deep |
| Multi-version comparison | Before/after |
| Strong narrative | Crisis-Turn-Revelation |
One main visual style (no overlapping): Table / comparison card / ASCII diagram / Callout, choose one as the dominant style.
Visual details (colors, fonts) are determined by the "Style" selected by the user in Stage 1.
Stage 5 · Writing: TL;DR + Topic Sentence + Counterexample + Exit
5.1 Opening TL;DR / Hook (placed upfront, cannot be buried): Stripe / Google SRE practice — first 2-3 sentences = full article summary. Choose one of three hooks: counterintuitive point / pain point / data impact.
5.2 Each paragraph starts with a topic sentence: State the conclusion first, then expand.
5.3 Each positive argument is paired with a counterexample / What not to do: Anthropic Docs practice, counterexample comparison is more effective than positive examples.
5.4 Provide an "exit" at the end: Reusable output + next action + boundary declaration (when it is not applicable).
5.5 Data with sources, no copying existing content: Link references (GitLab single source of truth).
5.6 Retrospective content: blameless principle: Focus on the issue, not the person.
5.7 Retrieval prompts: Opening summary sentence + end-of-section review + reusable mnemonic.
Stage 6 · Self-Check 5 Questions
Must go through these before finishing:
- Can someone who doesn't understand this topic understand it?
- Can readers retell the core content a week later?
- Does it still make sense if the longest paragraph is cut in half?
- Is each paragraph within one screen? (Linear One-Screen Test)
- Is it produced according to "completeness of detail level" instead of forcing to meet word count? (If background extensions/fictional cases/repeated scenarios are added to meet word count, remove them)
Anti-Pattern Checklist
| Anti-Pattern | Stage | Consequence |
|---|
| Skip Stage 1 and start writing directly | 1 | Self-satisfaction / deviation from requirements |
| Ask more than 4 questions at once | 1 | Excessive cognitive burden on users |
| Repeat questions for parameters already provided by users | 1 | Verbose / appears unintelligent |
| Define goal as "readers understand" | 2 | Information summary instead of transferable tool |
| 5 parallel core points | 3 | Working memory overload |
| Fail to distinguish parallel vs dependency chain | 3 | Structural confusion |
| List menus without giving recommendations | 4 | AI lets users choose 5 structures |
| Overlap main visual styles (use table + card + diagram together) | 4 | Visual overload |
| No "Current Configuration + Additional Prompt" bar at the top of HTML | 4 | Users don't know the basis of the output or that they can request adjustments |
| Force to add methodology extensions / fictional cases / repeated scenarios to meet word count | 3-5 | Fluff, the 5th self-check question is designed for this |
| No active persuasion when user selects "Teaching Version" for single-document materials | 1.5 | Inevitably fluff + user expectation mismatch (actual tests show README-like materials start to fictionalize when exceeding 5,000 words) |
| Expose "reference word count" to users in configuration bar / tables | 3 / File Rules | User expectations are anchored to word count, and they feel "deceived" when the count is not met |
| TL;DR buried in the middle | 5 | Readers leave within the first 30 seconds |
| No counterexample comparison | 5 | Positive examples are prone to misuse |
| Data without sources | 5 | Prone to fabrication |
| Copy existing content into the document | 5 | Information drift |
| Blame specific individuals in retrospectives | 5 | Violates blameless principle |
| Deliver without self-check after writing | 6 | Long / verbose / hard to read |
Quick Decision Tree
Trigger
↓
[Stage 1] AskUserQuestion 4 questions (unless already specified)
↓
[Stage 1.5] Material volume self-check → single document + Teaching Version → active persuasion to switch version
↓
[Stage 2] Define goal = what reusable item?
↓
[Stage 3] 3 core points + half-cut test
↓
[Stage 4] Main structure + main visual style (no overlap)
↓
[Stage 5] TL;DR + topic sentence + counterexample + exit
↓
[Stage 6] Self-check 4 questions → cut / split / adjust
↓
HTML output (add confirmation bar at top) + open in browser
Output File Rules
Must Add "Current Configuration + Additional Prompt" Bar at the Top of HTML
Each generated HTML must include this two-line bar below the Hero section and above the main content:
html
<div class="config-bar">
<div class="config-line">
📋 Current Configuration · Audience: [Answer to Question 1] · Goal: [Answer to Question 2]
· Detail Level: [Answer to Question 3] (approx. [Reading Time]) · Style: [Answer to Question 4]
</div>
<div class="hint-line">
💬 Too short? Tell me "Expand [Chapter Name]" / "Add [Background/Case/Reusable Framework]"
Too long? "Cut to key points" / "Merge Chapter X and Chapter Y"
</div>
</div>
Why add additional prompt: Length is a post-experience feeling, and even the most accurate pre-estimation may have "almost there" moments. Explicitly turn "almost there" into actionable instructions, so users can iterate without restarting the process. This is a supporting mechanism for this skill's intentional choice not to rigidly fix word count.
Why only show reading time instead of word count in configuration bar: Reading time is a perceptible commitment for users, while word count is an internal target for AI. Forcing to meet word count will lead to fluff when materials are insufficient, or lose content when materials exceed the count. Removing word count from user view avoids expectation mismatch like "marked 5,000-8,000 words but delivered 3,000" (this mismatch is equivalent to the old version's "unable to meet the count").
File Path
Default to write into the project's
directory:
docs/[Content Topic]-[YYYYMMDD].html
If the project does not have a docs/ directory, write into the user-specified path or current directory.
Automatically Open After Writing
After writing the HTML file, run
to open it in the browser for review.
Maintenance Rules
This checklist is cross-validated from three perspectives (writing / cognitive science / top company practices). If new sources (a classic writing book, a company's best practice) are worth adding, filter them by the standard "whether all three perspectives recognize it".
Anti-Principle: Do not add check items that "may be useful but not mandatory" to the checklist. AI incurs costs when following the checklist, so each added item must confirm that it can prevent a specific anti-pattern.