POC/Experiment Skill

Create Proof of Concept and Experiment documents (3-8 pages) that capture hypothesis validation, technology evaluations, or feasibility studies — culminating in a clear Go/No-Go recommendation backed by evidence.

Key principle: All information comes from the user. Do NOT scan the codebase. The Read tool is only for reading user-provided context files that the user explicitly shares.

When to Use a POC/Experiment Document

• Validating a technical hypothesis before committing to full implementation
• Evaluating a new technology or framework for adoption
• Assessing feasibility of an uncertain approach
• Documenting the results of a time-boxed technical spike
• Capturing evidence for a Go/No-Go decision on a risky approach

Workflow

Phase 1: Gather Context

Parse what the user already provided. Determine whether the POC is:

• Planned (writing before conducting): Help define hypothesis, success criteria, and approach
• Completed (documenting results): Capture findings and formulate recommendation

Only ask for what's genuinely missing.

Essential questions (use references/question-bank.md patterns, ask only if not already provided):

1. Hypothesis: "What specific hypothesis are you testing? (e.g., 'We believe X can achieve Y performance under Z conditions')"
2. Motivation: "What problem or decision is this POC trying to resolve?"
3. Approach: "How did you (or will you) conduct the experiment? What did you build or test?"
4. Success criteria: "How do you define success? What results would lead to Go vs No-Go?"
5. Results/Findings (if completed): "What did you find? Share key metrics, observations, or outcomes."
6. Limitations: "What are the limitations of this POC? What did it NOT test?"
7. Recommendation: "Based on the findings, what's your recommendation: Go, No-Go, or needs more investigation?"
8. Next steps: "If Go, what's the path to production? If No-Go, what alternatives exist?"
9. Related context (optional): "Any existing ADRs, RFCs, or tickets this informs?"

If the user is planning (not yet run) the POC: Focus on defining a rigorous hypothesis and measurable success criteria before the experiment begins.

If user needs research on technology options: Offer agent:web-research-specialist before or during the context gathering phase.

Rich context (accept at any point):

• Benchmark results or logs → use Read tool or accept pasted data
• Experiment code → capture key findings without scanning codebase
• Performance charts → incorporate key numbers into narrative

Phase 2: Generate & Iterate

Once sufficient context is gathered, generate the complete POC/Experiment document using the template from assets/templates/template.md.

Content generation rules:

• Use section headings from template.md exactly
• The Go/No-Go Decision section is MANDATORY — be explicit and unambiguous
• Support the recommendation with concrete evidence from the findings
• Document limitations honestly — a POC that overstates its conclusions is dangerous
• Use tables or lists for metrics and comparative results
• Do NOT include checkboxes, HTML comments, guidance questions, or quality criteria in output

After presenting the full draft:

1. Internally validate against assets/templates/quality-checklist.md — never show to user
2. Check that the recommendation is backed by the findings
3. Ensure limitations are clearly stated
4. Iterate based on feedback
5. Save in requested format

Document Structure

Key sections (from assets/templates/template.md):

Section	Purpose
Executive Summary	TL;DR of hypothesis, approach, and Go/No-Go
Problem Statement	What prompted the POC, current pain, success criteria
Approach & Solution Design	How the experiment was designed and conducted
Implementation Details	What was built, technologies used, time-boxed scope
Results & Findings	Quantitative and qualitative outcomes
Trade-offs & Limitations	What the POC does NOT prove, scope constraints
Recommendation & Next Steps	MANDATORY Go/No-Go decision with rationale
Appendix	Raw data, code snippets, detailed logs

Quality Principles

• Go/No-Go must be explicit — "maybe" or "it depends" without further qualification is not a recommendation
• Results must be supported by evidence — don't let subjective impressions outweigh data
• Limitations must be honest — future readers will use this to make real decisions
• Success criteria should have been defined before the POC (if planning), or explicitly stated before results
• A No-Go with clear learnings is more valuable than an inconclusive Go

Visual Aids

Graphs, comparison tables, and architecture diagrams strengthen POC documents. When requested:

1. Ask what the diagram should show (test setup, performance comparison, architecture)
2. Invoke common-engineering:mermaid skill for flowcharts and diagrams
3. For data charts, format results as tables in markdown

Integration Points

Capability	When to Use
agent:web-research-specialist	Research technology options, find comparable benchmarks
common-engineering:mermaid	Experiment setup diagrams, architecture comparisons
document-skills:docx	Export to Word format
document-skills:pdf	Export to PDF format

Reference Files

File	Purpose
references/writing-guidelines.md	Technical writing best practices
references/question-bank.md	AskUserQuestion patterns for this skill
assets/templates/template.md	Document structure (use for output)
assets/templates/guidance.md	Section-by-section guidance (read, never copy to output)
assets/templates/quality-checklist.md	Internal validation (never show to user)
assets/templates/examples.md	Completed examples for quality reference