--- name: document-superpowers description: "Complete document writing workflow with four stages: brainstorming → planning → execution → review. Use when user wants to write articles, blog posts, technical docs, or any long-form content." ---

# Document Superpowers

A systematic writing workflow that produces professional-quality articles, blog posts, and documentation.

## When to Use This

**Trigger this skill when the user wants to:** - Write a blog post - Create technical documentation - Draft an article or essay - Produce any long-form content (>500 words) - Write something that needs structure and quality

**Key phrases that should trigger:** - "Write a blog post about..." - "I need to create documentation for..." - "Help me write an article..." - "I want to write about..."

## Overview

Document Superpowers enforces a four-stage writing process:

``` 💡 Brainstorming → 📋 Planning → ✍️ Execution → 🔍 Review ```

Each stage has strict gates - you cannot skip ahead without completing the previous stage.

## The Four Stages

### Stage 1: Brainstorming **Skill:** `document-superpowers:brainstorming`

**What it does:** - Asks clarifying questions one at a time - Understands audience, purpose, core message - Presents topic brief for approval - Saves approved brief

**Output:** `docs/writing/YYYY-MM-DD-<topic>-brief.md`

**Next:** Automatically invokes `writing-article-plan`

### Stage 2: Planning **Skill:** `document-superpowers:writing-article-plan`

**What it does:** - Creates detailed section-by-section outline - Specifies key points, evidence needs, word counts - Plans transitions between sections - Identifies research requirements upfront

**Output:** `docs/writing/YYYY-MM-DD-<topic>-plan.md`

**Next:** Offers choice of execution mode

### Stage 3: Execution **Skills:** - `document-superpowers:executing-article-plan` (batch mode) - `document-superpowers:subagent-driven-writing` (iterative mode)

**What it does:** - Writes sections according to plan - Self-checks each section - Provides checkpoints for human review - Merges into full draft

**Output:** - Section drafts: `docs/writing/drafts/YYYY-MM-DD-<topic>/section-N-*.md` - Full draft: `docs/writing/YYYY-MM-DD-<topic>-draft.md`

**Next:** Automatically invokes `reviewing-article`

### Stage 4: Review **Skill:** `document-superpowers:reviewing-article`

**What it does:** - Four-pass systematic review: 1. Logic (is it sound?) 2. Evidence (is it supported?) 3. Flow (is it smooth?) 4. Polish (is it clean?) - Categorizes issues by severity - Documents all fixes - Produces final article

**Output:** - Review log: `docs/writing/YYYY-MM-DD-<topic>-review.md` - Final article: `docs/writing/YYYY-MM-DD-<topic>-final.md`

## Quick Start

### For Users

1. Say: "I want to write about [topic]" 2. Answer brainstorming questions 3. Approve the brief 4. Approve the plan 5. Choose execution mode (batch or iterative) 6. Review checkpoints as writing progresses 7. Approve final article

### For Agents

1. **Detect writing intent** - Look for phrases like "write", "create article", "blog post" 2. **Invoke brainstorming** - Start with questions, never skip to writing 3. **Follow the chain** - Each skill invokes the next automatically 4. **Enforce gates** - Do not skip stages or write before planning 5. **Provide checkpoints** - Regular human validation points

## File Structure

A complete writing project creates:

``` docs/writing/ ├── YYYY-MM-DD-topic-brief.md # Stage 1 output ├── YYYY-MM-DD-topic-plan.md # Stage 2 output ├── drafts/YYYY-MM-DD-topic/ # Stage 3 working directory │ ├── section-1-intro.md │ ├── section-2-argument.md │ └── ... ├── YYYY-MM-DD-topic-draft.md # Stage 3 output ├── YYYY-MM-DD-topic-review.md # Stage 4 review log └── YYYY-MM-DD-topic-final.md # Stage 4 final output ```

## Execution Modes

### Batch Execution (Default) - Write 2-3 sections at a time - Checkpoint after each batch - Fewer interruptions, longer focus - **Good for:** Straightforward articles, experienced writers

### Subagent-Driven (Advanced) - Fresh subagent per section - Two-stage review (spec + quality) - Tight feedback loop - **Good for:** Complex articles, high-stakes content, learning the system

## Key Principles

### 1. No Skipping Brainstorming Every article goes through all four stages. Even "simple" topics need briefs (they can be short, but they must exist and be approved).

### 2. One Question at a Time Don't overwhelm users with forms or multiple questions. Build understanding through conversation.

### 3. Bite-Sized Sections Sections are 150-400 words - small enough to write in one sitting, large enough to develop an idea.

### 4. Checkpoints Not Marathons Review after every 2-3 sections. Catch issues early.

### 5. Four-Pass Review Each review pass focuses on one dimension. Don't mix logic checking with grammar checking.

## Anti-Patterns to Avoid

❌ **"This is too simple to need a brief"** - Every article needs a brief, even if it's three sentences

❌ **Writing before planning** - Always create the plan before executing

❌ **Skipping self-checks** - Validate each section before moving on

❌ **Marathon writing sessions** - Use checkpoints every 2-3 sections

❌ **Single-pass review** - Four passes catch more issues than one combined pass

## Example Usage

See `examples/typescript-blog-post.md` for a complete walkthrough.

**Quick example:** ``` User: "I want to write a blog post about code reviews"

Agent: [invokes brainstorming] "Who's your target audience?"

User: "Junior developers"

Agent: "What should they do after reading?"

User: "Write better code review comments"

Agent: [continues questions → presents brief → gets approval] Agent: [creates plan → offers execution choice]

User: "Batch execution"

Agent: [writes sections 1-3] Agent: "Checkpoint: sections 1-3 complete. Continue?"

User: "Yes"

Agent: [completes draft → runs review → fixes issues] Agent: "Article complete and ready for publication!" ```

## Integration with Other Skills

Document Superpowers works well with:

- **Research skills** - Gather evidence during planning stage - **SEO skills** - Optimize keywords during review - **Publishing skills** - Export to Medium/WordPress after finalization - **Style guide skills** - Enforce organization standards in review

## Troubleshooting

**Agent skips brainstorming:** - Ensure skill descriptions are registered - Check HARD-GATE tags in brainstorming/SKILL.md

**Sections too long/short:** - Adjust word targets in the plan - Review if key points need more/less development

**Review finds no issues:** - Review may be too shallow - Try providing specific examples of what to look for - Check if four passes are actually happening

**Subagent fails repeatedly:** - Plan may be unclear - revise specifications - Consider switching to batch execution - Add more context to task briefs

## Files in This Skill

``` document-superpowers/ ├── SKILL.md # This file (entry point) ├── README.md # Full documentation ├── skills/ │ ├── brainstorming/SKILL.md # Stage 1 │ ├── writing-article-plan/SKILL.md # Stage 2 │ ├── executing-article-plan/SKILL.md # Stage 3 (batch) │ ├── subagent-driven-writing/SKILL.md # Stage 3 (iterative) │ └── reviewing-article/SKILL.md # Stage 4 └── examples/ └── typescript-blog-post.md # Complete walkthrough ```

## Next Steps

**To use this skill:** 1. Install the skills in your agent's skills directory 2. Say "I want to write about [topic]" 3. Follow the prompts through each stage 4. Get publication-ready content

**To learn more:** - Read `README.md` for full documentation - See `examples/typescript-blog-post.md` for walkthrough - Check individual `skills/*/SKILL.md` files for stage details

---

**Pro tip:** Trust the process. It feels slower at first but produces better results faster than iterative rewrites.