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

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

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.