Fires when

• ▸user wants to draft a decision doc, RFC, PRD, technical spec, design doc, or proposal
• ▸user mentions "write a doc", "draft a proposal", "create a spec", "write up"
• ▸skill author or PM is starting a substantive piece of writing where blind spots will be costly
• ▸user has rich context to transfer and wants Claude to interview them out of it
• ▸user has access to subagents (Claude Code) and wants a fresh-Claude reader test before sending the doc

Skip when

• ✕user just wants a short-form doc, a quick template, or one-shot prose (workflow overhead exceeds value)
• ✕user has no substantive context to transfer ("write me a generic doc") — Stage 1 has no documented short-circuit and will burn turns before it figures this out
• ✕user is in a runtime with no artifact/file write surface AND no markdown working directory (the "create the scaffold" branches both assume one or the other)
• ✕reader-testing the doc with a fresh Claude is the explicit non-goal (e.g. the doc is private or contains secrets that should not enter a subagent context)

Takes

• prompt:natural-language an opening request to write a doc + iterative chat for context-gathering, brainstorming, curation, and refinement
• text:info-dump user's raw context (background, history, politics, constraints, related threads); pasted prose, no schema required
• file:template optional — an existing doc template the user wants to follow (workflow uses it to skip the "suggest sections" branch in Stage 2)

Returns

• file:markdown a multi-section document built section-by-section with explicit clarify → brainstorm → curate → draft → refine cycles; in our run produced a 1,950-word decision doc with sharper structure than a one-shot prompt would have given
• text:reader-test-findings when subagents are available (Claude Code), Stage 3 produces a real gap report from a fresh-Claude read of the finished doc — in our run it caught 3 gaps the author hadn't noticed (missing DRI, undefined acronym, vague analytics migration plan)

Install

• notes: Nothing to install. This skill is a prompt-only workflow — a SKILL.md the agent reads and follows. The only 'runtime requirement' is the host being able to write markdown files (or render artifacts) for the section-by-section drafting loop, and ideally subagent access for Stage 3.

No requirements.txt, no scripts, no fixtures. The entire skill is one ~16 KB SKILL.md. Capability gating is documented inline ('If access to artifacts is available...' / 'If access to sub-agents is available...') — Claude Code gets the full experience; claude.ai web gets a manual variant of Stage 3.

Caveats

• no install at all — the skill is a SKILL.md and nothing else. Good (zero deps) but means there is also nothing to lint, no version pin, no schema check; the workflow lives or dies on the agent following it faithfully
• Stage 1 has no documented exit branch for "user has no substantive context to transfer." On thin prompts ("write me a doc") the workflow loops through 5 meta-questions, an info-dump request, and 5-10 clarifying questions before producing a generic template — high overhead with no payoff. SKILL.md should add an early-exit detector
• Stage 3 (Reader Testing) is gated on subagent access. In Claude Code it runs automatically and is the most valuable piece of the workflow — in our run it surfaced 3 real gaps the author had missed. On claude.ai the user must do it manually by opening a fresh chat, which most users will skip
• the "use create_file / use str_replace" guidance assumes a host that exposes those tools as artifact primitives; in environments that only have raw file I/O the workflow still works but the "provide artifact link after every change" instructions become no-ops
• no integrations were available in our run (no Slack/Drive MCP). The SKILL.md branches for those cases (cleanly), but the linked threads and prior RFCs the user mentioned could not be pulled in, only described — a real loss of fidelity. The skill correctly nudges the user to enable connectors but cannot itself install them
• no token / latency cost guidance. A full run is ~50 minutes of chat and probably 30-60k input tokens by the time Reader Testing finishes. For short docs that ratio is bad; SKILL.md should warn users to use the workflow for docs that will be read by more than one person
• "never reprint the whole doc" / "always use str_replace" is good guidance but unenforced — an agent that ignores it will burn context fast on long docs without anything in the skill catching the regression