---
name: whitepaper-builder
description: End-to-end skill for creating strategic whitepapers and analytical documents. Produces versioned Markdown documents with executive summary, market analysis, competitive landscape, persona tables, solution deep-dives, architecture diagrams, growth models, phased roadmaps, honest risk assessment, and comprehensive references. Supports cross-agent review for argument coherence and architecture quality.
tools-needed: file read/write, shell execution, user interaction
---

# Whitepaper Builder Skill

## Purpose

Create a comprehensive, evidence-backed strategic whitepaper from a North Star document and plan (produced by `idea-refiner` or `north-star-builder`). Output is a single versioned Markdown file with 15-19 sections that builds a complete strategic case - from market opportunity through solution architecture to implementation roadmap.

This skill produces strategic whitepapers, not academic papers. The structure follows the pattern: establish the market -> define the problem -> introduce the solution -> deep-dive features -> show how it all connects -> prove it is buildable -> acknowledge risks -> recommend next steps.

## When To Use

- User asks to create a whitepaper, strategic document, or comprehensive analysis
- A North Star and plan exist (from idea-refiner or north-star-builder) or user provides equivalent context
- The document needs to persuade stakeholders with evidence, architecture, and a credible roadmap
- Content requires 10+ sections with diagrams, tables, and structured argumentation

## Output Format

File: `<slug>-whitepaper-v<N>.md`

---

## Document Template

The whitepaper must contain these sections in order. Sections marked _(optional)_ can be omitted when not applicable to the product. All other sections are required.

```markdown
# <Title> - Strategic Whitepaper (v<N>)

> **Author:** <name>
> **Date:** <date>
> **Version:** v<N>
> **Status:** Draft | In Review | Published

---

## Table of Contents

1. Executive Summary
2. The Market Opportunity
3. The Problem
4. Competitive Landscape
5. Who Are We Solving For?
6. The Solution
7. What <Product> is NOT
8-12. <Deep-Dive Sections - 3-5 sections per major feature/engine>
13. Integration Architecture
14. Growth Model
15. Platform/Chain-Specific Advantages _(optional)_
16. Bootstrapping Strategy
17. Implementation Approach
18. Risks & Mitigations
19. Recommended Next Steps
20. References

---

## 1. Executive Summary

<2-3 paragraphs that a decision-maker can read in 60 seconds and understand:>
<- What the product is and what problem it solves>
<- Why the market opportunity exists now>
<- What makes this approach uniquely positioned>
<- What the ask is (team, timeline, resources)>

<This is written LAST, after all other sections are complete. It should accurately summarize the final content.>

## 2. The Market Opportunity

<Data-driven section establishing market size, growth trajectory, and timing.>

<Include a data table:>

| Metric | Value | Source |
|--------|-------|--------|
| <metric> | <value> | <source> |

<Follow the table with 2-3 paragraphs interpreting the data: why is this market attractive? Why now? What macro trends support this opportunity?>

## 3. The Problem

<Narrative section establishing the pain point. Do not just list problems - tell the story of the problem.>

<Include a diagram showing the problem visually - how things work today, where the breakdown happens:>

```mermaid
graph TD
    A["Current State"] --> B["Limitation"]
    B --> C["User Pain"]
```

<2-4 paragraphs: what specifically is broken, who suffers, what the cost of inaction is, why existing solutions fail to address it.>

## 4. Competitive Landscape

<Analysis of existing players - what they do well, where they fall short.>

<Structure as per-competitor analysis:>

**<Competitor 1> (<key metric>):**
- <strength 1>
- <strength 2>
- <limitation relevant to the problem>

**<Competitor 2> (<key metric>):**
- <strength 1>
- <limitation>

**The gap no one fills:**
<1-2 paragraphs on what the market is missing that this product provides>

## 5. Who Are We Solving For?

<Persona table identifying target users>

| Who | Primary Need | Pain Today | Our Value |
|-----|-------------|------------|-----------|
| <persona 1> | <need> | <current pain> | <what we give them> |
| <persona 2> | <need> | <pain> | <value> |
| <persona 3> | <need> | <pain> | <value> |

<1-2 paragraphs expanding on the primary persona and why they matter most>

## 6. The Solution

<High-level overview - what the product is and how it works at a conceptual level. Do NOT go deep into features yet; that is what the deep-dive sections are for.>

<Include a high-level architecture or ecosystem diagram:>

```mermaid
graph TD
    A["Component 1"] --> B["Component 2"]
    B --> C["Component 3"]
    A --> D["Component 4"]
```

<2-3 paragraphs: the core insight, the approach, why it works. Keep it conceptual - details follow in deep-dive sections.>

## 7. What <Product> is NOT

<Explicit anti-positioning. Address the most common misconceptions head-on.>

- **<Product> is not <misconception 1>.** <One sentence explanation of what it actually is.>
- **<Product> is not <misconception 2>.** <Explanation.>
- **<Product> is not <misconception 3>.** <Explanation.>

<This section builds credibility by showing self-awareness and preventing readers from mapping the product to the wrong mental model.>

## 8-12. Deep-Dive Sections

<3-5 sections, one per major feature, engine, or system component. Each follows the same pattern:>

### <Feature/Engine Name>

<2-4 paragraphs explaining what this is, why it matters, and how it works.>

<Mermaid diagram showing the feature's flow, architecture, or interaction pattern:>

```mermaid
<appropriate diagram type>
```

<Additional detail: specific mechanics, examples, edge cases.>

<If the feature has distinct modes, options, or configurations, use a table:>

| Mode/Option | Description | When to Use |
|-------------|-------------|-------------|
| <mode> | <description> | <use case> |

## 13. Integration Architecture

<How all the deep-dive components work together as a system. This section connects the dots.>

<Include an integration diagram showing interactions between all major components:>

```mermaid
graph TD
    subgraph "System"
        A["Component 1"] --> B["Component 2"]
        B --> C["Component 3"]
        C --> D["Component 4"]
        D -->|"feedback"| A
    end
```

<2-3 paragraphs explaining the integration patterns, data flow between components, and why this architecture supports the product's goals.>

## 14. Growth Model

<How success compounds - the flywheel, network effects, or growth loop that makes the product stronger over time.>

<Include a flywheel/growth loop diagram:>

```mermaid
graph TD
    A["Trigger"] --> B["Action"]
    B --> C["Outcome"]
    C --> D["Reinforcement"]
    D --> A
```

<2-3 paragraphs explaining why growth accelerates over time, what the key inflection points are, and how to measure flywheel velocity.>

## 15. Platform/Chain-Specific Advantages _(optional)_

<When the product has deployment flexibility or platform-specific benefits, document them here.>

<If applicable, include a diagram showing deployment options or platform interactions.>

## 16. Bootstrapping Strategy

<How the product solves the cold-start problem. Every new product faces this - how do you get the first users when the product's value depends on having users?>

<2-3 paragraphs: what comes first, how to build initial traction, how to transition from bootstrapping to organic growth.>

## 17. Implementation Approach

### Phased Roadmap

| Phase | Milestone | Key Deliverables | Timeline |
|-------|-----------|-----------------|----------|
| 1 | <milestone> | <deliverables> | <timeline> |
| 2 | <milestone> | <deliverables> | <timeline> |
| 3 | <milestone> | <deliverables> | <timeline> |
| 4 | <milestone> | <deliverables> | <timeline> |

<1-2 paragraphs per phase explaining what is delivered, why this ordering makes sense, and what each phase proves.>

### Security Approach

<Security considerations for the implementation - not exhaustive (that belongs in a tech arch doc), but enough to show security is a first-class concern.>

### Technology Stack

<Brief overview of key technology choices with rationale. Do not replicate a full tech arch document - highlight the choices that matter most for the whitepaper's audience.>

## 18. Risks & Mitigations

| Risk | Severity | Likelihood | Mitigation |
|------|----------|------------|------------|
| <risk> | High/Med/Low | High/Med/Low | <mitigation> |

### Honest Assessment

<This subsection is mandatory. Acknowledge weaknesses directly.>

<What are you least confident about? Where might the approach not work? What assumptions could prove wrong? What external dependencies could fail?>

<This builds credibility. A whitepaper that acknowledges its risks is more trustworthy than one that pretends to have none.>

## 19. Recommended Next Steps

<Numbered list of concrete, actionable next steps. Not vague ("explore options") but specific ("Hire 2 senior mobile engineers with real-time multiplayer experience").>

1. <Specific action with who, what, and when>
2. <Specific action>
3. <Specific action>
4. <Specific action>

## 20. References

| # | Source | URL |
|---|--------|-----|
| 1 | <source description> | <url> |
| 2 | <source description> | <url> |
```

---

## Source-Verified Fact Bank (Recommended Truth Layer)

The Fact Bank is idea-forge's **truth layer** - the structured evidence substrate that makes a claim agent-citable, not just human-credible. In an AI-mediated discovery economy, a whitepaper is read first by an agent answering "should I trust this?" and only second by a human; provable, structured claims are what survive that reading, while emotional/adjective claims get averaged into the category. Empirically, citations and statistics each raise AI-citation visibility by roughly 30% (Princeton GEO study, 2026). For that reason the Fact Bank is **recommended by default for any externally published whitepaper**, not just citation-rigorous ones. For internal/throwaway drafts targeting business stakeholders, the Key Data Points table in the North Star and inline source references remain sufficient.

When using the Fact Bank:

| ID | Claim | Source URL | Verified Date |
|----|-------|-----------|---------------|
| F1 | <claim> | <url> | <date> |

Rules:
- Every factual claim references a Fact ID
- Claims without Fact IDs must be labeled as "the author's analysis" or "proposed framework"
- Volatile data (market stats, user counts) must include verification date
- URLs must be verified as live before publication

---

## Mermaid Diagrams

Strategic whitepapers must include Mermaid diagrams to make complex concepts accessible. Target **6-10 diagrams minimum** depending on document length and complexity.

### Required Diagrams

Every strategic whitepaper should have at minimum:

1. **Problem visualization** (graph TD) - shows where the current approach breaks down
2. **Solution architecture** (graph TD/LR) - high-level system overview
3. **Per-feature flow diagrams** (graph/sequenceDiagram) - one per deep-dive section
4. **Integration architecture** (graph TD with subgraph) - how components connect
5. **Growth flywheel** (graph TD with circular edges) - how success compounds

### ASCII Diagrams for Stack/Layer Visualizations

When showing positioning within a larger ecosystem (e.g., where a product fits in a technology stack), ASCII diagrams are sometimes clearer than Mermaid. Use ASCII only for simple stack/layer diagrams where Mermaid's graph structure adds unnecessary complexity.

```
Example:
+---------------------------+
|      Application Layer    |
+---------------------------+
|      Product Layer  <---  |
+---------------------------+
|      Protocol Layer       |
+---------------------------+
|      Network Layer        |
+---------------------------+
```

### Diagram Style Rules

- **Non-technical whitepapers**: 6-12 nodes max, descriptive labels, max 3-4 words per line
- **Technical whitepapers**: 8-20 nodes, technical labels where the audience expects them
- **Never use `\n` or `<br/>` in Mermaid node labels** - neither renders reliably (Notion cuts multi-line text). Keep labels on one line; shorten if too long.
- Solid arrows (`-->`) for direct flows; dotted arrows (`-.->`) for optional/indirect
- Use `subgraph` sparingly - only for logical grouping of 2+ related nodes
- No emojis in diagrams
- Place the diagram **immediately after** the paragraph introducing the concept
- Every diagram must be self-explanatory

### Diagram Types by Use Case

| Content Type | Mermaid Type | When to Use |
|---|---|---|
| Architecture layers | `graph TD` | System stacks, protocol layers |
| Process flows | `graph LR` or `graph TD` | User journeys, deployment flows |
| Interaction sequences | `sequenceDiagram` | API calls, multi-party flows |
| State machines | `stateDiagram-v2` | Lifecycle stages, status transitions |
| Feedback cycles | `graph TD` with circular edges | Growth loops, flywheels |
| Component relationships | `classDiagram` | Module dependencies, data models |

---

## Writing Rules

1. **Strategic structure, not academic.** This is not Abstract-Introduction-Body-Discussion-Conclusion. This is Market-Problem-Solution-DeepDive-Roadmap-Risks-NextSteps. The reader is a decision-maker, not a peer reviewer.

2. **Evidence before claims.** Establish market data and competitive landscape before presenting the solution. The reader should understand WHY before WHAT.

3. **Persona table is mandatory.** Section 5 must include a table mapping personas to needs, pains, and value delivered. This keeps the whitepaper grounded in real user needs.

4. **Anti-positioning builds credibility.** The "What X is NOT" section prevents mischaracterization and shows self-awareness. Never skip it.

5. **Deep-dives are the substance.** Sections 8-12 are where the whitepaper earns its length. Each deep-dive should be detailed enough that a reader understands the feature's mechanics, not just its existence. Include diagrams, tables, and examples.

6. **Integration architecture connects the dots.** After deep-dives, show how everything works together. Without this section, the whitepaper is a feature list, not an architecture.

7. **Growth model shows compounding value.** Explain why the product gets better over time - network effects, data moats, community, flywheel mechanics.

8. **Honest assessment is mandatory.** The Risks section must include a subsection that directly acknowledges weaknesses. A whitepaper that hides risks loses credibility with sophisticated readers.

9. **Recommended Next Steps are specific.** Not "explore partnerships" but "Identify and approach 3 gaming studios with South Asian mobile gaming expertise for co-development discussions by Q2."

10. **Executive Summary is written last.** Draft it after all sections are complete. It should accurately summarize the final content in 2-3 paragraphs.

11. **Quantify everything possible.** "Large market" -> "500M+ active mobile gamers in South Asia (Source: Newzoo)." Every claim that can be quantified should be.

12. **No marketing language.** Whitepapers argue with evidence, not enthusiasm. Remove superlatives, exclamation marks, and promotional phrases. Avoid superlatives like "revolutionary" or "game-changing." Prefer factual claims: "First to offer 32-player Ludo matches."

13. **Use hyphens (-) or semicolons (;) instead of em-dashes** in all generated content.

14. **No redundant explanations across sections.** Each concept, technology, or data point is explained fully ONCE at its primary section. Later sections reference it briefly ("as described in Section 8") but do not re-explain. If a technology (e.g., HIP-1215) appears in 4+ sections, consolidate the explanation into one definitive section and reference from the others. Redundancy dilutes impact and adds length without value.

15. **Revenue projections need a worked financial model.** If the whitepaper describes revenue sources, include at least one quantitative scenario: "At $X daily volume, the protocol generates $Y annually in fees. At Z% market share, this requires W daily active users." Decision-makers will ask "how much does this cost and when does it pay for itself?" - the whitepaper should answer that question with numbers, not just descriptions.

16. **Infrastructure whitepapers must address real-world utility, not just DeFi mechanics.** Enterprise readers ask "how will this be USED?" before "how deep is the liquidity?" If the product is infrastructure (AMM, lending, compliance layer), explain the downstream use cases: payments, settlement, cross-border transfers, loyalty programs, merchant acceptance. DeFi liquidity is a means, not an end. The whitepaper should articulate what applications become possible once the infrastructure exists.

17. **Address consortium and multi-party models when relevant.** For products serving multiple institutional issuers, consider whether a shared model (multiple banks issuing under one umbrella) is more compelling than individual deployments. Consortium models solve liquidity (pooled capital) and use case (combined merchant networks) problems simultaneously. If the product supports this, describe it explicitly.

---

## Mid-Draft Quality Check (Mandatory)

> **Foundation:** Inherits the quality framework (Mid-Draft Quality Check, Refine-or-Pivot, review tiers) from `skills/builders/builder-foundation/SKILL.md`. Whitepaper-specific prompts below.

### Whitepaper-Specific Quality Prompts

| Dimension | What to Look For |
|-----------|-----------------|
| **Depth** | Do deep-dive sections teach something specific about how features work, or just describe their existence? Would an investor learn implementation details? |
| **Originality** | Does the competitive analysis reveal non-obvious gaps? Does the honest assessment say something surprising? Or is this generic AI output? |
| **Coherence** | Does the narrative build logically from market opportunity to next steps? Could you remove any section without breaking the argument? |
| **Completeness** | Are all North Star must-covers addressed with substance (not just mentioned)? |

**Sprint contract pattern recommended** for whitepapers (typically 500+ lines). See builder-foundation for details.

**Document evaluator recommended** for whitepapers. See builder-foundation for invocation pattern.

---

## Cross-Agent Deliverable Review

After drafting, optionally run cross-agent review (mechanics in builder-foundation). For strategic whitepapers, the most valuable critics are Gemini (argument coherence) and Claude (architecture quality); Codex is optional for data verification. Whitepaper-specific critic prompts follow.

### Critic Roles

#### Gemini - Argument Coherence & End-to-End Logic

```
Review the following strategic whitepaper for argument coherence and logical completeness.

Verify:
1. The market opportunity data supports the stated thesis
2. The problem section creates genuine urgency - not manufactured urgency
3. Competitive analysis is fair and well-informed (not strawman competitors)
4. The solution logically addresses the stated problem
5. Deep-dive sections provide enough detail to be convincing
6. Integration architecture shows how components actually work together
7. Growth model is realistic - the flywheel has plausible mechanics
8. Bootstrapping strategy addresses the actual cold-start challenge
9. Implementation roadmap is phased credibly - not everything in Phase 1
10. Risks section is honest - are the real risks acknowledged?
11. The product as described is actually buildable and viable
12. No logical gaps between problem statement and solution
13. Anti-positioning section addresses the most likely misconceptions

Output format:
1) LOGICAL_GAPS (claims not supported by evidence, non-sequiturs)
2) ARGUMENT_COHERENCE (does the narrative build logically from market to next steps?)
3) FEASIBILITY_CONCERNS (is this actually buildable? does the growth model work?)
4) CREDIBILITY_ISSUES (hidden risks, unfair competitive analysis, manufacturing urgency)
5) READY_FOR_PUBLICATION (yes/no + reason)
```

#### Claude - Architecture Quality & Narrative Structure

```
Review the following strategic whitepaper for architecture quality and narrative structure.

Verify:
1. Document structure flows logically - each section builds on the previous
2. Deep-dive sections are detailed enough to be substantive (not just feature lists)
3. Diagrams are placed correctly and enhance understanding
4. Integration architecture section connects all deep-dive components
5. Persona table accurately reflects the target audience
6. Implementation roadmap phases are ordered for credibility (prove value early)
7. Technology stack choices are well-reasoned for the stated requirements
8. Section length is proportional to importance (deep-dives should be substantial)
9. Transitions between sections are smooth and purposeful
10. The whitepaper achieves the North Star's success criteria

Output format:
1) STRUCTURAL_ISSUES (sections out of order, missing transitions, disproportionate length)
2) DEPTH_ISSUES (sections that need more detail, features that are under-explained)
3) DIAGRAM_QUALITY (missing diagrams, poorly placed diagrams, unclear diagrams)
4) NARRATIVE_FLOW (does the whitepaper read as a cohesive argument or a feature list?)
5) READY_FOR_PUBLICATION (yes/no + reason)
```

#### Codex - Data Verification & Citation Accuracy (Optional)

```
Review the following whitepaper for data accuracy and citation correctness.

Verify:
1. All market data and statistics are current (flag anything older than 12 months)
2. All source URLs are live (LIVE / DEAD / REDIRECT)
3. Competitive data is accurate (download counts, features, pricing)
4. Technical claims are correct (protocol capabilities, platform features)
5. No unsourced assertions that should have citations
6. Reference table is complete and consistently formatted

Output format:
1) CITATION_ISSUES (dead URLs, misquoted data, wrong attributions)
2) OUTDATED_DATA (statistics that need refreshing)
3) MISSING_CITATIONS (claims without sources)
4) TECHNICAL_ERRORS (incorrect technical details)
5) READY_FOR_PUBLICATION (yes/no + reason)
```

### Review Procedure

1. Concatenate whitepaper content into inline prompts (never reference file paths - critics may not have file access)
2. Run critics in parallel with per-agent timeouts (Codex=480s, Gemini/Claude=180s)
3. Merge feedback, triage by severity, apply changes
4. If Codex times out, fall back to a general-purpose Claude sub-agent with web search for citation verification
5. Max 2 rounds for deliverable review

---

## Versioning

- **v1**: First draft from North Star + plan
- **v2**: After user feedback or cross-agent review
- **v3**: Final version

**Only keep the latest version.** Delete previous when new is created (e.g., delete `<slug>-whitepaper-v1.md` when `<slug>-whitepaper-v2.md` is written).

---

## Review Checklist

Before finalizing, verify items in priority order. Spend 70% of review effort on Critical Items (where Claude is weakest).

### Critical Items (Claude Weak Spots - Review Thoroughly)

- [ ] All numerical claims (TVL, market cap, dates, yields, user counts) verified against primary sources - research agents hallucinate dates and inflate numbers
- [ ] Canonical Glossary exists and every key noun (pool composition, token names, component names) appears in its canonical form throughout the document - grep for common variations to catch drift
- [ ] No vague internal references - every "Section N", "Step N", "Engine N", "Figure N", "steps X-Y" replaced with a descriptive name that makes sense without flipping between sections
- [ ] No redundant explanations across sections - each concept explained ONCE, referenced elsewhere (check: does any technology/data point appear in 4+ sections with full re-explanation?)
- [ ] Revenue projections include at least one worked financial model with volume assumptions, fee calculations, and break-even analysis
- [ ] Deep-dive sections teach specific mechanics, not just describe feature existence (depth test: would an investor or engineer learn something new?)
- [ ] At least 2 insights in the competitive analysis that are non-obvious (not the first thing anyone would say)
- [ ] Honest Assessment addresses real, specific risks beyond general market conditions - risks that specifically affect this approach
- [ ] No AI writing patterns - no significance inflation, no promotional language, no generic conclusions
- [ ] Growth model flywheel has plausible mechanics with specific triggers and feedback loops
- [ ] Anti-positioning addresses the most likely misconceptions (not strawmen)
- [ ] Bootstrapping strategy addresses the actual cold-start problem (not generic "build community" advice)

### Standard Items (Claude Strong Spots - Quick Verify)

- [ ] All Must Cover topics from North Star addressed
- [ ] No Must NOT Cover topics appear
- [ ] Executive Summary accurately summarizes the document (written last)
- [ ] Market data is sourced and current
- [ ] Persona table present; 3-5 deep-dive sections with diagrams
- [ ] Integration architecture connects all components
- [ ] Implementation roadmap is phased with specific milestones
- [ ] 6+ Mermaid diagrams present; references table complete
- [ ] No placeholder text; no marketing language; hyphens not em-dashes
- [ ] Tone matches North Star specification

---

## Lessons Learned

These patterns emerged from building strategic whitepapers and should be followed:

### Content

- **Market data establishes credibility early.** The reader decides whether to take the whitepaper seriously in the first two sections. Lead with real numbers.
- **Competitive analysis must be fair.** Strawman competitors undermine the entire document. Show genuine understanding of what competitors do well before explaining where they fall short.
- **Anti-positioning prevents the wrong mental model.** Readers will map your product to something they already know. The "What X is NOT" section controls that mapping.
- **Deep-dives earn the whitepaper's length.** A 15-page whitepaper with shallow feature descriptions is worse than a 5-page one-pager. Each deep-dive section must teach the reader something specific about how the feature works.
- **The honest assessment builds trust.** Sophisticated readers are more convinced by a whitepaper that says "we are least confident about X" than one that presents everything as certain.

### Process

- **North Star first.** Never write a whitepaper without a finalized North Star. The North Star's must-cover topics become the whitepaper's sections.
- **Map must-cover topics to sections before writing.** Create a section plan that shows which North Star topics map to which whitepaper sections. This prevents coverage gaps.
- **Write Executive Summary last.** It should summarize what was actually written, not what was planned.
- **Diagrams reduce word count.** A good Mermaid diagram replaces 2-3 paragraphs of explanation. Use them liberally.
- **Cross-agent review catches blind spots.** Gemini finds logical gaps. Claude finds structural issues. Together they cover what a single reviewer misses.

---

## Output Rules

- Write in <=200-line chunks; on output-limit, resume exactly where you stopped (see CLAUDE.md Output Token Limit Rule).

---

**Version:** 3.1.0