Brainstorm Proof-of-Concept Plan

Overview

Transform risky requirements into validated POC plans through parallel research, risk prioritization, and sequential validation. Use after design is complete but technical assumptions remain unproven.

Core principle: Validate riskiest assumptions first with minimal code, data-driven decisions, and clear go/no-go criteria.

When to Use

Use this skill when:

• Design complete (via brainstorming skill) but technical risks remain
• Requirements specify unfamiliar technologies or untested integrations
• Multiple competing approaches need validation (algorithm choice, library selection)
• Team needs confidence before committing to full implementation

Don't use for:

• Proven technologies with known patterns
• Design exploration (use brainstorming skill instead)
• Implementation planning (use writing-plans skill instead)

Workflow Position

brainstorming (design) → brainstorm-proof-of-concept-plan (validation) → writing-plans (implementation)

The Process

Use TodoWrite to track each step:

1. Identify Riskiest Assumptions

Review requirements and extract technical risks:

• Unfamiliar APIs or libraries
• Performance requirements without proof
• Integration patterns never attempted
• Competing technology choices (OT vs CRDT, REST vs GraphQL)

Prioritize by:

• Technical uncertainty (how much unknown)
• Architectural impact (affects other decisions)
• Failure cost (cost of discovering late)

2. Elicit Implicit Risks from User

Requirements often miss hidden assumptions. Use AskUserQuestion:

AskUserQuestion({
  questions: [{
    question: "Which risks should POC prioritize? I recommend [X] because [Y].",
    header: "POC Priority",
    multiSelect: false,
    options: [
      { label: "Risk A First", description: "Foundation for others..." },
      { label: "Risk B First", description: "Highest uncertainty..." },
      { label: "All Sequentially", description: "Validate each in order..." },
      { label: "Research First", description: "Need investigation before deciding..." }
    ]
  }]
})

Why: User may have domain knowledge that changes priority ("We already validated X, focus on Y").

3. Launch Parallel Research Agents (Agents Write Own Reports)

Critical: Each research agent writes its own report file. Main agent does NOT write research reports.

For 3+ research areas, dispatch Task agents simultaneously:

// Each agent writes directly to design-docs/research/
Task({
  subagent_type: "general-purpose",
  prompt: `Research VitePress WebSocket integration patterns.

**Output:** Write findings to design-docs/research/vitepress-websocket-integration.md

**Format:**
# VitePress WebSocket Integration Research

**Research Date:** YYYY-MM-DD
**Sources:** [URLs]

## Key Findings
- Finding (Source: URL)

## Implications for POC
- What this means

## Recommendation
[Data-driven choice]

**Use elements-of-style:writing-clearly-and-concisely skill for writing.**`
})

Launch 3-4 agents in parallel:

• Current system analysis (existing code/config)
• Technology comparison (Library A vs B)
• API/integration patterns (how others solved this)
• Performance characteristics (benchmarks, limitations)

Why parallel: 4x speed, each produces focused brief with citations.

Never: Write research reports yourself. Always delegate to Task agents.

4. Synthesize Research Findings

After research agents complete:

• Read all reports from design-docs/research/
• Identify common themes and conflicting recommendations
• Prepare synthesis for POC design decisions

You synthesize, but agents wrote the reports.

5. Design Sequential POCs (Document ALL POCs)

Critical: Document the COMPLETE POC strategy, not just the first POC.

Break validation into phases that build on each other:

Example:

• POC-1: Layout Override + Width Validation (foundation)
• POC-2: File-Based Diff Loading (build on POC-1)
• POC-3: TOC Integration in Left Nav (build on POC-2)

For the FIRST POC only: Create detailed design with:

• Goal (what we're validating)
• Success criteria (quantitative metrics)
• Timeline (days, not weeks)
• Implementation details (enough to build)
• Deliverable (working code or measurements)
• Go/no-go decision (proceed, pivot, or stop)

For REMAINING POCs: Document high-level:

• Goal (what risk it validates)
• Why it comes after previous POC (dependency)
• Rough timeline

Why: Complete strategy shows big picture. Detailed design for POC-1 enables immediate implementation.

6. Write POC Design Document

Location: Same folder as whiteboard/requirements documents

Naming pattern: Append -poc{{N}}-{{short-slug}} to the base filename

• Example: If requirements file is diff-view-monaco-requirements.md
• POC-1 becomes: diff-view-monaco-poc1-validate-diff-view-builds.md
• POC-2 becomes: diff-view-monaco-poc2-props-and-theme.md

Required sections:

• Problem (what risks we're validating)
• Approach (why this approach) - MUST cite requirements, research, or external sources
• Complete POC Strategy (ALL planned POCs with brief descriptions)
• Architecture (detailed for POC-N being built) - MUST cite requirements for each design decision
• Success Metrics (how we'll measure)
• Implementation Details (enough to build POC-N)
• Risk Mitigation (what if it fails)
• Out of Scope (what we're NOT validating) - MUST link to requirement IDs
• References (link to research/ files and external sources)

Citation Requirements: Every design decision MUST be backed by:

• Requirements document links: [FR-2.1](./requirements-file.md#^FR2-1)
• Research document links: [Research](./research/topic-research.md)
• External sources: [Source](https://url) with full URL

Format: Use markdown links with anchors for requirement references. Use relative paths ./ for same-folder files.

Example "Complete POC Strategy" section:

## Complete POC Strategy

### POC-1: Layout Override and Width Validation (This Document)
**Goal:** Prove we can disable right sidebar and achieve 600px+ per diff pane
**Timeline:** 2-3 days
**Status:** Detailed design below

### POC-2: File-Based Diff Loading
**Goal:** Validate SystemPromptDiff can load content from file paths
**Dependencies:** Requires POC-1 layout working
**Timeline:** 1-2 days
**Status:** Future

### POC-3: TOC Integration in Left Sidebar
**Goal:** Merge page TOC into left navigation sidebar
**Dependencies:** Requires POC-1 and POC-2 complete
**Timeline:** 3-4 days
**Status:** Future

Required: Use elements-of-style:writing-clearly-and-concisely skill for design doc.

Integration with Other Skills

Before this skill:

• brainstorming - Complete design with unproven assumptions

After this skill:

• writing-plans - Create implementation plan once POC validates approach

During this skill:

• elements-of-style:writing-clearly-and-concisely - Required for all documentation (by both main agent and research agents)
• Task tool - Dispatch parallel research agents who write their own reports

Common Rationalizations

| Rationalization | Reality | |----------------|---------| | "I'll write research reports myself" | Agents write their own reports. You synthesize. Delegate. | | "Just document POC-1, others are future work" | Document complete strategy. Detailed design for POC-1 only. | | "Parallel research is overkill" | Parallel = 4x speed with focused briefs. Always use for 3+ areas. | | "User already specified risks" | User lists known risks. AskUserQuestion surfaces hidden ones. | | "Documentation structure doesn't matter" | Same-folder location enables discovery. Always follow naming pattern. | | "Writing skill slows me down" | Concise docs save implementation time. Required for all reports. | | "POC planning is too formal" | POC without plan = random prototyping. Structure prevents waste. | | "Citations are obvious from context" | Future readers need explicit links. Always cite requirements/research/sources. | | "I'll add citations later" | Design decisions without citations = unverifiable claims. Add during writing. | | "General approach doesn't need citations" | Every design choice needs backing. Cite requirements or research for all decisions. |

Success Criteria

POC plan succeeds when you can answer:

1. Which risks need validation (prioritized list)
2. What sequence to validate them (complete POC strategy with ALL identified POCs)
3. How to measure success for POC-1 (quantitative criteria)
4. What to build for POC-1 (minimal scope with implementation details)
5. What to do if it fails (pivot options)

All answers backed by research with citations (written by research agents).

Quick Reference

| Step | Action | Tool | Who Writes | |------|--------|------|------------| | Identify risks | Extract from requirements | Analysis | You | | Prioritize | Matrix (uncertainty × impact × cost) | Judgment | You | | Elicit hidden risks | Ask which matters most | AskUserQuestion | You | | Research | 3+ areas simultaneously | Task (parallel) | Agents write reports | | Synthesize | Read reports, find themes | Read tool | You | | Design POCs | ALL POCs + detailed POC-1 | docs/plans/ | You | | Validate | Build minimal code, measure | Next step | Future |

Real-World Impact

Speed: Parallel research saves hours compared to serial investigation.

Quality: Research citations (from agent reports) enable verification.

Clarity: Complete POC strategy prevents "what comes next?" confusion.

Delegation: Research agents write reports while you orchestrate and synthesize.