Tool adaptation
The AskUserQuestion in the text uses the current platform's structured questioning tool; if that tool is unavailable, use a single message to clarify the same four dimensions. Parameters the user has already specified are inherited directly; a different tool name does not block writing.
Cross-validated across three sources: comprehensive writing theory (Zinsser, On Writing Well / Heath, Made to Stick / Rosenfeld, Information Architecture) + learning science (Sweller CLT / Brown, Make It Stick / Wiggins backward design) + big-tech documentation practice (Stripe / GitLab / Linear / Anthropic / Google SRE).
Meta-principles (placed at the very top, recite silently before each start)
- If you yourself gain no new understanding after reading it, the reader won't either. Writing is thinking on paper, not filling in a template.
- The endpoint is "the reader can use it next time", not "the reader can understand it this time". Backward design: first think about what "reusable tool" the reader will have in hand after reading (a comparison table / a judgment framework / a decision path / a mnemonic), then work backward to what to write.
- Don't list a menu — give a recommendation + a one-sentence reason. AI likes to "list 5 options for you to choose from", but good documentation dares to be opinionated.
Trigger conditions
Trigger(medium-to-long HTML content meant for people to read):
- "Do a retrospective / summary / roundup / organize"
- "Make a tutorial / study guide / getting-started doc"
- "Explain X clearly / organize it into readable HTML"
- "Make a report / explanatory doc"
- Any request to produce > 500 words of structured reading content
Do not trigger(short output / operational / non-HTML needs):
- Writing code / fixing bugs / editing files
- Answering in one or two sentences
- Code diff / short list
- The user explicitly says "answer in markdown" / "just say it in chat"
- PRD (use prd-test-writer) / article writing (use writing-assistant) / naming (use product-naming)
Important: this skill producesonly one format: HTML. If the user wants markdown, do not use this skill.
Operating mode
触发
↓
阶段 1：强制用 AskUserQuestion 一次性问 4 个关键问题
↓
用户选完
↓
阶段 2-6 在 AI 心里走（不对用户念稿）
↓
产出 HTML，顶部加「本次配置」确认条，浏览器自动打开
Exceptions(skip the questions in stage 1):
- The user has already specified all 4 parameters in the prompt (e.g. "a 5K-word retrospective for PMs, storytelling style")
- The user explicitly says "do it quickly" / "just give me anything" / "don't ask"
Stage 1 (mandatory): use AskUserQuestion to ask all 4 at once
You must use the AskUserQuestion tool to initiate a single inquiry, containing the 4 questions below.The question wording and options can be slightly adjustedbut the dimensions cannot be changed.
Question 1: Who is it for? (Audience)
| Option | Description |
|---|---|
| PM / Product Manager | Leans toward story, benchmarking, decisions, reusable frameworks |
| Engineer / technical newcomer | Includes code snippets, technical decisions, hands-on guide |
| Executive / decision-maker | TL;DR + data + invest/pass recommendation |
| Self / memo | Timeline + note-style, for reference |
| External users / customers | Tutorial-style, building concepts step by step |
Question 2: What do you take away after reading? (Destination)
| Option | Description |
|---|---|
| Decision basis | After reading, can go/no/hold |
| Operating steps | After reading, can take action |
| Concept understanding | After reading, know what it is |
| Story resonance | After reading, feel moved |
| Memo archive | After reading, can look it up later |
Question 3: How detailed should it be?
Design rationale: Word count is a post-hoc impression and often cannot be promised (forcing a word count when material is insufficient leads to padding). Therefore,word count does not enter the user view, and only two things the user can perceive are promised—"what is included" and "reading time」。
| Option | What is included | Reading time |
|---|---|---|
| Quick-read card | TL;DR + 1 core framework / 1 main diagram, shareable | 3 minutes |
| Standard version (default recommendation) | Core points + story + counterexample + exit | 5-8 minutes |
| Teaching version | + background extension + multi-perspective comparison + reusable framework + boundary statement | 20-30 minutes |
| AI chooses | Derived backward from "audience tolerance time × number of independent information points in the material" | — |
How to determine word count(AI internal reference, not told to the user, no word-count promise written in the configuration bar):
- Reading speed is derived backward at 300 Chinese characters/minute for PM/product-type content.
- Quick-read card → internal target ~800 characters | Standard version → ~1.5K-2.5K characters | Teaching version → ~5K-8K characters
- What truly determines when to stop writing is whether every item in the "what is included" checklist is covered thoroughly(standard's four things—"core points / story / counterexample / exit"—are all complete; teaching has 4 additional extension items), not "the word count has been reached."
Stage 1.5 (mandatory): Material volume self-check + proactive pushback
After Question 4 is answered and before entering Stage 2, the AI must perform a self-check.There is only one scenario that triggers pushback：
- Single-document-type material(a single README / a single PRD / a single article) and the original text is < 3K characters + the user selected "Teaching version」
After triggering, the AI must interrupt the process and proactively push back to the user：
⚠️ A heads-up: you selected the teaching version (20-30 minutes of reading), but the material is a single [README/PRD/article] of only X characters. Forcing it to teaching-version depth would make about 60% of the content AI extrapolation (background extension / comparison / framework), not the original material. It is recommended to choose one of two options: ① Change to "Standard version"(5-8 minutes), which exactly covers the material's current depth ② Supply 2-3 more pieces of similar material(multiple PRDs / multiple articles in the same domain / all project documents), so the teaching version has a real stage
Continue with the teaching version? (Continue / Switch to standard version / I'll go supply material)
- User switches tier: follow the new tier through Stages 2-6
- User goes to supply material: wait until the user finishes supplying material, then continue
- User insists on continuing with the teaching version: only then produce it, and it must include a 'Material Volume Warning' banner + a 'Deduction' label on each deduction passage (see output rules for details)
Multi-source material / non-teaching version → does not trigger counter-persuasion, goes directly to Stage 2.
Question 4: Style + emphasis (merged)
Each option binds 'visual tone + content emphasis':
| Option | Visual | Content emphasis |
|---|---|---|
| Engineering seriousness | Fresh blue (Stripe/Linear style) | Lessons and methodology-focused |
| Story-driven reading | Warm scholarly tones (off-white + dark brown) | Story completeness-focused |
| Decision conciseness | Minimalist black and white (Apple documentation style) | Data impact-focused |
| Technical depth | Dark tech (GitHub Dark) | Includes code details |
| AI chooses | — | Recommend based on audience defaults |
After the user finishes choosing, write the 4 parameters into the 'This Configuration' section at the top of the HTML (see 'Output File Rules' below).
Stages 2-6 (the AI goes through these internally, does not recite them to the user)
Stage 2 · Define the endpoint (backward design)
Based on the 'what will they have after reading' the user chose in Stage 1, further specify: what extra thing will the reader have in hand after reading"Reusable things"？
- A comparison table (how to choose between A vs B)
- A judgment framework (when to do X)
- A decision path (when encountering Y → first a → then b)
- A mnemonic (short and easy to remember)
- A checklist
Anti-pattern: the endpoint is set only as far as 'the reader understands'.: The endpoint is set only to "reader understanding."
Stage 3 · Identify the core points (≤ 3)
Iron rule of working memory(Sweller's cognitive load theory): a new reader can only process 3-4 new chunks at a time.Default 3, maximum 5; anything beyond that must be merged or downgraded to an appendix。
Relationships between the core pointsMust be explicitly thought through:
- [Parallel] 3 independent key points, readable in any order
- [Dependency chain Why → What → How] must be in order
Halving test: after listing all candidate points, ask 'if only half could be kept, which ones would remain'—what remains is the true backbone.
Stage 4 · Choose the main structure (one, do not stack them)
Warning: this stage is where it's easiest to 'demonstrate cognitive overload yourself'—give a recommendation + a one-sentence reason, do not list a menu.
1 main structure(choose based on the nature of the content):
| Nature of content | Recommended structure |
|---|---|
| A process / multi-step decision | Timeline |
| Multiple parallel topics | Categorized chapters |
| Solve a specific problem | Problem-oriented Q&A |
| Teaching / concept scaffolding | Progressive teaching gradient from shallow to deep |
| Multi-version comparison | before/after |
| Strong storytelling | Crisis - turning point - insight |
1 main visual set(Do not stack): table / comparison card / ASCII diagram / Callout, choose one dominant one.
Visual details (colors, fonts) are determined by the "style" the user chose in Phase 1.
Phase 5 · Write: TL;DR + thesis sentence + counterexample + exit
5.1 Opening TL;DR / hook(Front-loaded, cannot be buried): Stripe / Google SRE practice—the first 2-3 sentences = the full-text summary. Choose one of three hooks: counterintuitive / pain point / numerical shock.
5.2 Each paragraph starts with a thesis sentence: State the conclusion first, then elaborate.
5.3 Pair each positive argument with a counterexample / What not to do: Anthropic Docs practice; counterexample contrast is more effective than positive examples.
5.4 Give an "exit" at the end: reusable artifact + next action + boundary statement (when it does not apply).
5.5 Data carries sources; do not copy existing content: link citations (GitLab single source of truth).
5.6 Retrospective content: blameless principle: focus on the issue, not the person.
5.7 Retrieval cues: one summary sentence at the beginning + review at the end of each section + reusable mnemonic.
Phase 6 · 5 self-check questions
Must pass before finishing:
- Can someone who does not understand this understand it?
- Can they restate the core a week after reading?
- If the longest paragraph were cut in half, would it still make sense?
- Is every paragraph within one screen?（Linear One-Screen Test）
- Was it produced according to the "level-of-detail completeness," rather than padded just to hit a word count?(If background extensions / fictional cases / repeated similar scenarios were added just to hit the word count, cut them.)
Master anti-pattern checklist
| Anti-pattern | Which phase | Consequence |
|---|---|---|
| Skipping Phase 1 and starting to write directly | 1 | Self-indulgence / going off track |
| Asking more than 4 questions at once | 1 | Excessive user cognitive load |
| Repeatedly asking for parameters the user has already given | 1 | Wordy / appears unintelligent |
| Setting the endpoint at "reader understanding" | 2 | Information aggregation rather than a transferable tool |
| 5 core points listed side by side | 3 | Working memory overload |
| Not distinguishing parallel items vs dependency chains | 3 | Chaotic structure |
| Listing a menu without giving a recommendation | 4 | AI lets the user choose among 5 structures |
| Stacking main visuals (using table + card + diagram all together) | 4 | Visual overload |
| No "this configuration + additional notes" bar at the top of the HTML | 4 | The user does not know what baseline it was produced from, nor that they can add more |
| Adding methodology extensions / fictional cases / repeated scenarios just to hit a word count | 3-5 | Padding; self-check question 5 exists specifically for this |
| Choosing the "teaching version" for single-document material without triggering proactive dissuasion | 1.5 | Inevitable padding + misaligned user expectations (testing shows README-type material starts fabricating once it goes past 5K) |
| Writing "reference word count" in config bars / tables exposes it to users | 3 / File rules | User expectations get anchored by word count; when it can't be met, it feels like "you lied to me" |
| TL;DR buried in the middle | 5 | Readers leave in the first 30 seconds |
| No counterexample comparison | 5 | Positive examples are easily misused |
| Data has no source | 5 | Easy to fabricate |
| Copying existing content in the docs | 5 | Information drift |
| Calling out specific people in the retrospective | 5 | Violates blameless |
| Delivering right after writing without self-check | 6 | Long / verbose / hard to read |
Quick decision tree
触发
↓
[阶段 1] AskUserQuestion 4 问（除非已明确）
↓
[阶段 1.5] 素材体量自检 → 单文档 + 教学版 → 主动反劝改档
↓
[阶段 2] 定终点 = 可复用的什么？
↓
[阶段 3] 3 个核心点 + 砍半测试
↓
[阶段 4] 主结构 + 主视觉（不叠）
↓
[阶段 5] TL;DR + 论点句 + 反例 + 出口
↓
[阶段 6] 自检 4 问 → 砍 / 拆 / 调
↓
HTML 输出（顶部加确认条）+ 浏览器打开
Output file rules
A 「this run's config + add-on prompt」 bar must be added at the top of the HTML
Every HTML output must include a two-line bar like this below the Hero section and above the body:
<div class="config-bar">
<div class="config-line">
📋 本次配置 · 受众：[问题 1 答案] · 终点：[问题 2 答案]
· 详略：[问题 3 答案]（约 [阅读时间]） · 风格：[问题 4 答案]
</div>
<div class="hint-line">
💬 觉得短？告诉我「展开 [章节名]」/「加 [背景/案例/可复用框架]」
觉得长？「砍到要点」/「合并 X 章和 Y 章」
</div>
</div>
Why add the add-on prompt: Length is a post-hoc feeling; even if you're accurate beforehand, there will always be a "just a bit off." Making that "just a bit off" explicit as clickable instructions lets users iterate without rerunning. This is the mechanism paired with this skill's deliberate choice not to hard-code word counts.
Why the config bar only shows reading time and not word count: Reading time is a promise users can perceive, while word count is an internal AI target. When the material can't reach the word count, forcing it leads to padding; when it overshoots, cutting it loses content. Remove word count from the user view to avoid expectation misalignment like "labeled 5K-8K but given 3K" (this kind of misalignment is equivalent to the old version "not being able to stick to it").
File path
By default, write into the project docs/ under:
docs/[内容主题]-[YYYYMMDD].html
If the project has no docs/, write to the user-specified path or the current directory.
Automatically open after writing
After writing the HTML file, run open <path> to open it in the browser for review.
Maintenance rules
This checklist is cross-validated from three perspectives (writing / cognitive science / big-company practice). If there's a new source (some classic writing book, some company's best practice) worth adding, screen it by the standard of "do all 3 sides approve?"
Anti-principles: Do not add "possibly useful but not required" checklist items. Running through a checklist itself has a cost for the AI, and every added item must be confirmed to prevent some specific anti-pattern.