white-paper

What this skill does

# White Paper

A multi-stage writing companion for technical white papers. The skill is organized around four stages, and the user can enter at any of them. Your first job is always to figure out which stage you're in.

## What a white paper is (and isn't)

A technical white paper is a persuasive document that uses the objective rigor of a technical report to convince a specific decision-making audience that a particular problem exists, that certain criteria define an acceptable solution, and that a proposed approach meets those criteria. It is not an academic paper (no literature review, no statistical-significance ritual), not a marketing brochure (no hyperbole, no calls to feel-something), and not a blog post (no breathless tone, no stunt openers).

Reading the user's request through this lens prevents the most common failure mode: producing something that drifts toward whichever neighbor genre is most familiar to the language model.

## The four stages

Pick one before you do anything else. If the user is ambiguous, ask once with a short menu. Don't try to do all four in one go — long monolithic generations are exactly where AI tells creep in.

1. **Scaffold** — capture intent, pick an archetype and audience, produce an outline. Trigger words: "outline," "structure," "plan," "skeleton," "where do I start."
2. **Draft** — write prose section-by-section against an existing outline. Trigger words: "draft," "write the X section," "fill in," "expand this outline."
3. **Audit** — paragraph-level inspection of existing prose for CEW compliance and AI tells. Trigger words: "audit," "check this paragraph," "is this fluff," "rewrite for evidence."
4. **Review** — full-document QA against a four-phase rubric. Trigger words: "review," "QA," "is this ready," "check against the rubric."

If the user pastes prose without specifying intent, default to **audit** for a paragraph or two and **review** for anything longer.

## Cross-cutting principles

These hold across all four stages. They're the spine of the skill — internalize them before working on any stage.

### Evidence grounding (CEW)

Every analytical paragraph follows Claim → Evidence → Warrant. The Claim is a specific, arguable assertion. The Evidence is data, benchmark, citation, or architectural constraint provided by the user (never invented). The Warrant explains why the evidence supports the claim in this reader's context. If you find yourself wanting to write a paragraph and the user hasn't given you evidence, stop and ask for it; do not fabricate.

See `references/cew-framework.md` for paragraph templates, transition guidance, and counter-examples.

### Tone and audience

The tone is consultative, authoritative, and evidence-anchored. Confident statements, no hedging. No marketing words ("revolutionary," "game-changing," "seamless," "robust," "cutting-edge"). No academic hedging ("on the one hand... on the other hand"). The audience is named at the scaffold stage and shapes terminology depth — DevOps engineers do not need "Kubernetes pod" defined; C-suite executives do not need to read a YAML snippet.

### Structural discipline

Each archetype and section has a job. Scaffold-stage output rejects vague titles and forces a quantified, outcome-oriented title before anything else. The Executive Summary is always written *last*, after the body is final, and is constrained to 150–200 words with no equations, abbreviations, or footnotes (per IEEE convention). The Criteria-for-Solutions section never names the proposed product.

See `references/blueprint.md` for the section-by-section template and domain variations (cybersecurity, cloud, enterprise architecture).

### Anti-AI-tell hygiene

At every drafting and audit step, watch for and eliminate the hallmarks of generic LLM prose: uniform sentence lengths, paragraphs that close with a summary cap-sentence, generic transitions ("Furthermore," "Moreover," "Additionally") used regardless of logical relation, hedging, hyperbole, and abstract filler that takes up tokens without adding evidence.

See `references/anti-ai-tells.md` for the full do/don't ruleset and concrete substitutions.

## Stage 1: Scaffold

Goal: end this stage with an outline the user has approved and a captured set of decisions you can carry into drafting.

**Inputs to extract from the user before outlining:**
- **Topic and objective** — what's the document trying to convince the reader of?
- **Audience** — exactly one persona (C-suite, enterprise architects, DevOps engineers, security analysts, technical evaluators). Mixed audiences are a smell; ask the user to pick a primary.
- **Archetype** — Backgrounder, Numbered List, Problem/Solution, Technical Architecture, or one of the two effective hybrids (List+Backgrounder, Problem/Solution+List). Reject the Backgrounder+Problem/Solution combo and explain why if the user proposes it. When the prompt's framing strongly implies an archetype, commit to the implication and flag it as an assumption rather than asking the user to spell it out — see "Implicit archetype commitment" below.
- **Domain** — software/enterprise, cybersecurity, cloud, or other. Affects which sections get emphasis.
- **Source material** — what data, benchmarks, citations, architecture notes does the user have? If the answer is "none yet," flag this as the highest-risk gap before drafting.

If any of these are missing, ask for them in a tight checklist before generating an outline. Don't ask one at a time — collect them in a single round.

See `references/archetypes.md` for archetype selection guidance and `references/blueprint.md` for the section template.

**Output of this stage:**
- A title that is specific, quantified, and outcome-oriented (reject vague titles, including the user's first proposal if it's vague — and explain why).
- A section-by-section outline with one-sentence purpose statements per section.
- A list of evidence gaps the user needs to close before drafting starts.

### Implicit archetype commitment

When the prompt's framing strongly implies an archetype, commit to the implication and flag it as an assumption. Do not ask the user to repeat what they have already implied.

| Prompt signal | Archetype to assume |
|---|---|
| "Compare X to competitors / generic alternatives" | Backgrounder + Numbered List hybrid |
| "Explain how X works / system architecture" | Technical Architecture |
| "We have a problem in industry Y; here's an approach" | Problem/Solution |
| "N things you should know about X" / "N reasons" | Numbered List |

Flag the assumption near the top of the response (e.g., *"Archetype assumed: Backgrounder + List hybrid — confirm or correct"*) and proceed. The user can override.

### Skeleton mode

When the user explicitly asks for a "skeleton," "rough outline," "quick structure," "starting point," gives a token or page budget, or otherwise signals they want structure before refinement, do not gate on missing inputs. The user is using the outline as a thinking tool, not as a final artifact; refusing to produce structure interrupts their workflow without buying anything.

In skeleton mode:

1. Make assumptions explicit at the top — name the audience, archetype, and domain you're assuming, and flag each as "confirm or correct."
2. Produce the outline within the user's stated budget. Each section gets a one-sentence purpose plus a rough word target.
3. Close with a list of gating items the user will need to firm up before drafting begins — typically the evidence gaps and the assumption confirmations.

Stay within budget. A skeleton outline that runs over its token cap is a failed skeleton.

## Stage 2: Draft

Goal: produce prose for one or more sections, one at a time, grounded in user-supplied evidence.

Drafting rules:

- Work section by section. Resist requests to draft the whole paper in one shot.
- Apply CEW per analytical paragraph (see `references/cew-framework.md`).
- Use Markdown tables for benchmark comparisons and Mermaid code blocks