Writing Brainstorm Skill

Writing Brainstorm

Generate writing topics and gather references from Readwise highlights.

When to Use

Invoke this skill for:

Discovering what to write about from reading patterns
Gathering sources and references for a known topic
Finding thematic connections across highlights
Building an outline with supporting quotes

Prerequisites

This skill requires the Readwise MCP server. The plugin auto-configures it, but the READWISE_TOKEN environment variable must be set.

Setup (if MCP not working):

Get API token from https://readwise.io/access_token
Set environment variable: export READWISE_TOKEN=your_token
Verify: claude mcp list should show readwise

Critical: Sub-Agent Pattern for Readwise Searches

NEVER call search_readwise_highlights directly from the main chat. Raw search results return 50-100+ highlights, polluting context and degrading conversation quality.

ALWAYS use parallel sub-agents (one per search theme) to:

Execute the search
Filter and deduplicate results
Return a condensed summary

Sub-Agent Pattern

For a topic with N distinct themes, launch N parallel sub-agents using the Task tool:

Task(
  subagent_type="general-purpose",
  model="haiku",  # Fast and cheap for filtering
  prompt="""Search Readwise for highlights about **[THEME]**.

Use `mcp__readwise__search_readwise_highlights` with:
- vector_search_term: "[semantic search terms]"
- full_text_queries: [{"field_name": "highlight_plaintext", "search_term": "[keyword]"}]

Return ONLY:
- Top 3 most relevant sources (title, author)
- Top 3 quotes worth citing (with source attribution)
- 1-2 sentence theme summary"""
)

Example: Law Review on Private Equity Access

Launch 5 parallel agents:

"private equity retail investors democratization"
"accredited investor definition regulation"
"401k retirement private markets"
"interval fund tender offer evergreen"
"investor protection paternalism securities"

Each returns ~100 words instead of ~5000 words of raw highlights.

Two Modes

Discovery Mode

When user wants to find topics ("what should I write about?"):

Fetch tag landscape
- Use get_tags to see all topic clusters
- Present tags grouped by frequency/recency
Analyze recent reading
- Use get_recent_content to fetch recent highlights
- Identify recurring themes, authors, or concepts
Semantic pattern detection
- Examine highlights for cross-cutting themes
- Look for: tensions, debates, unanswered questions, surprising connections
Present topic candidates
- For each potential topic, show:
  - Theme description
  - Supporting highlights (2-3 examples)
  - Relevant tags
  - Potential angle or thesis

Gathering Mode (Progressive Workflow)

When user has a topic ("gather sources on X"), follow this human-in-the-loop workflow:

Phase 1: Clarify Intent

BEFORE any search, use AskUserQuestion to understand:

AskUserQuestion(questions=[
  {
    "question": "What's your primary angle or thesis for this piece?",
    "header": "Angle",
    "options": [
      {"label": "Critique existing framework", "description": "Argue current approach is flawed"},
      {"label": "Propose reform", "description": "Offer specific policy changes"},
      {"label": "Comparative analysis", "description": "Compare approaches across jurisdictions"},
      {"label": "Empirical analysis", "description": "Present data-driven findings"}
    ],
    "multiSelect": false
  },
  {
    "question": "Who is your target audience?",
    "header": "Audience",
    "options": [
      {"label": "Law review", "description": "Academic legal audience"},
      {"label": "Practitioners", "description": "Lawyers, regulators, compliance"},
      {"label": "Policy makers", "description": "Legislators, agency staff"},
      {"label": "General educated", "description": "Informed non-specialists"}
    ],
    "multiSelect": false
  }
])

Phase 2: Search Sources

Decompose into themes based on clarified intent
- Break the topic into 3-6 distinct search themes
- Each theme becomes a parallel sub-agent search
Launch parallel sub-agents
- Use the Task tool with model="haiku" for each theme
- Run all searches in a single message (parallel execution)
- See "Sub-Agent Pattern" section above
Synthesize results
- Deduplicate sources across agent responses
- Identify the strongest quotes from each theme
- Note gaps (themes with few/no highlights)

Phase 3: Draft Outline → `OUTLINE.md`

Save the outline to a file for iteration:

# OUTLINE.md

## Working Title
[Title]

## Thesis
[One-sentence claim]

## Target Audience
[From Phase 1]

## Structure
### I. Introduction
### II. [Section]
### III. [Section]
...

## Key Sources
[Deduplicated from Phase 2]

## Open Questions
[Gaps to address]

Ask for feedback on the outline before proceeding.

Phase 4: Section Deep-Dive

For each major section, use AskUserQuestion to refine:

AskUserQuestion(questions=[
  {
    "question": "For Section II (Background), what level of detail do you need?",
    "header": "Depth",
    "options": [
      {"label": "Brief context", "description": "1-2 paragraphs, assume reader familiarity"},
      {"label": "Full background", "description": "Comprehensive treatment for general reader"},
      {"label": "Synthesis only", "description": "Synthesize precedents without detailed summaries"}
    ],
    "multiSelect": false
  }
])

Create SECTION-II-OUTLINE.md with:

Section thesis/purpose
Key arguments in order
Supporting sources mapped to arguments
Anticipated counterarguments

Repeat for each section, getting human feedback before moving to prose.

Output Format

Produce a markdown outline:

# [Topic Title]

## Thesis/Angle
[One-sentence framing]

## Key Sources
- **[Source 1]** by [Author]
  - "[Highlight quote]"
  - Relevant to: [subtopic]

## Outline
### [Subtopic 1]
- Point A (Source 1, Source 3)
- Point B (Source 2)

### [Subtopic 2]
...

## Open Questions
- [Questions highlights don't answer]

## Next Steps
- Suggested writing skill: /writing-[domain]

Domain Detection

After gathering sources, detect the topic domain and suggest the appropriate writing skill:

| Domain Indicators | Suggested Skill | |-------------------|-----------------| | Legal cases, statutes, law reviews, constitutional | /writing-legal (Volokh) | | Economics, markets, policy, data, empirical | /writing-econ (McCloskey) | | General/other | /writing (Strunk & White) |

Readwise MCP Tools

Primary tools for brainstorming:

| Tool | Use Case | Direct Call OK? | |------|----------|-----------------| | get_tags | Survey topic landscape | ✅ Yes | | get_recent_content | See current reading themes | ✅ Yes | | search_readwise_highlights | Find highlights by keyword | ❌ Sub-agent only | | get_highlights | Retrieve with filters | ⚠️ Use caution (can be large) | | get_books | Browse source library | ✅ Yes |

Why sub-agents for search? A single search can return 50-100 highlights (~5000+ tokens). Multiple searches compound this. Sub-agents filter to essentials before returning to main context.

File Output Convention

Save brainstorming artifacts to the project's docs/ or scratch/ directory:

project/
├── docs/
│   └── writing/
│       ├── OUTLINE.md              # Main article outline
│       ├── SECTION-I-OUTLINE.md    # Introduction details
│       ├── SECTION-II-OUTLINE.md   # Background details
│       └── ...
└── scratch/
    └── brainstorm-notes.md         # Working notes (gitignored)

Workflow Examples

Discovery Mode Example

User: "I want to write something but don't know what"

Process:

Fetch tags → find clusters like "antitrust", "market-power", "regulation"
Get recent highlights → notice many from economics sources
Analyze → tension between "consumer welfare" and "market structure" keeps appearing
Present → "Potential topic: The consumer welfare standard debate. You have 12 highlights across 4 sources discussing this tension. Angle: Why market structure matters beyond prices."
Domain detection → Economics sources detected → "Use /writing-econ for drafting"

Gathering Mode Example (Progressive)

User: "Let's brainstorm a law review article about retail access to private equity"

Process:

Clarify → AskUserQuestion: angle (critique/reform/comparative), audience (law review/practitioners)
User responds → "Critique existing framework, law review audience"
Decompose → 5 themes: PE retail access, accredited investor, 401(k) access, fund structures, investor protection
Search → Launch 5 parallel Haiku sub-agents
Synthesize → Dedupe sources, extract best quotes, note gaps
Save → Write docs/writing/OUTLINE.md
Feedback → "Here's the outline. Any sections to add/remove/reorder?"
User responds → "Add comparative section on EU ELTIF"
Deep-dive → AskUserQuestion per section, create SECTION-II-OUTLINE.md
Handoff → "Outline complete. Use /writing-legal to draft."

Integration

After brainstorming:

/writing - General prose drafting
/writing-econ - Economics/finance articles
/writing-legal - Law review articles
/ai-anti-patterns - Check for AI writing indicators

Agent Skills: Writing Brainstorm

Skill Files