proof-of-concept

name	proof-of-concept
description	Rapid validation of technical feasibility and approach before full implementation. Use when evaluating new technologies, validating approaches, testing integrations, or demonstrating feasibility to stakeholders.

Proof of Concept (PoC)

Core Principle

Prove the concept, not the implementation. Learn fast, decide faster.

Good PoCs:

• Have clear success criteria — Know what you're validating
• Are time-boxed — Days, not weeks
• Focus on risk — Test what you're unsure about
• Lead to decisions — Go/no-go with evidence
• Are disposable — Code gets thrown away, knowledge doesn't

---

When to Use

Use this skill when:

• Evaluating new technologies or frameworks
• Validating technical approaches before committing
• Making architectural decisions with unknowns
• Testing third-party integrations
• Demonstrating feasibility to stakeholders
• De-risking major technical initiatives
• Choosing between competing solutions

Do NOT use a PoC when:

• Requirements are clear and solution is known
• Technology is already familiar to the team
• Time pressure requires immediate production work
• The problem is small enough to just solve directly

---

PoC vs Prototype vs MVP

Proof of Concept (PoC)

• Purpose: Validate technical feasibility
• Audience: Technical team
• Duration: 1-5 days
• Quality: Throwaway code
• Outcome: Go/no-go decision

Prototype

• Purpose: Explore UX/design
• Audience: Designers, stakeholders
• Duration: 1-2 weeks
• Quality: Functional but not production-ready
• Outcome: Design validation

MVP (Minimum Viable Product)

• Purpose: Test market fit
• Audience: End users
• Duration: Weeks to months
• Quality: Production-ready but minimal
• Outcome: Product-market validation

---

PoC Planning

Step 1: Define Success Criteria

Before writing any code, answer these questions:

What question are we answering?

• ✅ "Can we migrate 10M records from MySQL to PostgreSQL without downtime?"
• ✅ "Does GraphQL reduce our API payload size by >30%?"
• ✅ "Can WebRTC handle our video conferencing requirements?"
• ❌ "Is GraphQL good?" (Too vague)

What does success look like?

• Measurable outcomes
• Pass/fail criteria
• Performance benchmarks
• Integration validation

Example Success Criteria:

## Success Criteria

1. ✅ Authentication flow works with our existing OAuth provider
2. ✅ Page load time < 2 seconds with 1000 items
3. ✅ Can integrate with our existing API gateway
4. ✅ Team can understand and modify code after 1-hour tutorial
5. ❌ Production-ready error handling (out of scope)

---

Step 2: Identify Key Risks

What are we unsure about?

Focus the PoC on your biggest unknowns:

Technical Risks:

• Performance (will it be fast enough?)
• Integration (will it work with our systems?)
• Scalability (will it handle our load?)
• Security (does it meet our requirements?)

Team Risks:

• Learning curve (can we learn it quickly?)
• Documentation (is it well-documented?)
• Ecosystem (are there libraries we need?)
• Support (can we get help when stuck?)

Operational Risks:

• Deployment (can we deploy it?)
• Monitoring (can we observe it?)
• Maintenance (who will maintain it?)
• Cost (is it within budget?)

---

Step 3: Set Time Boundaries

PoCs should be time-boxed.

PoC Scope	Time Budget
Simple integration	1-2 days
Technology evaluation	2-3 days
Complex system integration	3-5 days
Architecture pattern validation	3-5 days

If you need more than 5 days, you're building too much.

Strategies for staying on time:

• Use time boxing (e.g., 2-hour chunks)
• Cut scope ruthlessly
• Focus on one thing at a time
• Stop when you have your answer

---

Step 4: Determine Scope

What to Include ✅

Core Validation:

• The feature/capability you're testing
• Integration with critical systems
• Performance benchmarks (if relevant)
• Security basics (if applicable)

Example: Testing a new search engine

• ✅ Index sample data (1000-10000 records)
• ✅ Implement basic search query
• ✅ Measure query response time
• ✅ Test with realistic data volume
• ✅ Verify relevance of results

What to Exclude ❌

Production Concerns:

• ❌ Comprehensive error handling
• ❌ Edge case coverage
• ❌ Full test suite
• ❌ Scalability optimizations
• ❌ Complete UI/UX
• ❌ Deployment infrastructure
• ❌ Monitoring and alerting
• ❌ Documentation (beyond PoC notes)
• ❌ Security hardening
• ❌ Performance optimization

Example: Testing a new search engine

• ❌ Full production data (millions of records)
• ❌ Advanced filtering features
• ❌ User authentication
• ❌ Caching layer
• ❌ Distributed deployment
• ❌ Query analytics

---

PoC Execution Process

Phase 1: Research (20% of time)

Before coding, do your homework:

1. Read official documentation

   • Getting started guides
   • Architecture overview
   • Best practices

2. Find working examples

   • Official examples
   • GitHub repositories
   • Tutorial projects

3. Check compatibility

   • Language/framework versions
   • Operating system requirements
   • Dependency conflicts

4. Identify potential blockers

   • Known limitations
   • Missing features
   • Integration challenges

---

Phase 2: Minimal Setup (10% of time)

Get to "Hello World" as fast as possible:

1. Use scaffolding tools

   • Framework CLIs (create-react-app, rails new, etc.)
   • Starter templates
   • Docker containers

2. Skip optional setup

   • Linters (unless testing DX)
   • CI/CD
   • Testing frameworks
   • Code formatters

3. Use hosted services

   • Managed databases
   • Cloud functions
   • SaaS integrations

Goal: Write domain code, not boilerplate

---

Phase 3: Core Implementation (50% of time)

Build the minimum to test your hypothesis:

Focus on:

• The specific feature/integration you're validating
• Realistic data (not "hello world")
• Critical path functionality
• Key integration points

Example Structure:

poc-new-search/
├── README.md              # What we're testing
├── setup.sh               # How to run
├── src/
│   ├── index.js           # Core search implementation
│   └── integration.js     # Integration with our API
├── data/
│   └── sample-data.json   # Realistic test data
└── results.md             # Findings

Code Quality Expectations:

• Working code (not production code)
• Comments on key decisions
• No tests (unless testing is what you're evaluating)
• Hardcoded values are fine
• Copy-paste is acceptable

---

Phase 4: Testing Against Criteria (15% of time)

Validate your success criteria:

1. Functional Testing

   • Does it work?
   • Does it integrate?
   • Does it solve the problem?

2. Performance Testing (if relevant)

   • Basic benchmarks
   • Realistic data volumes
   • Identify bottlenecks

3. Developer Experience (if relevant)

   • Setup time
   • Code clarity
   • Debugging experience

Document your findings as you go.

---

Phase 5: Documentation (5% of time)

Capture your learnings:

1. What worked?
2. What didn't work?
3. What surprised you?
4. What questions remain?

See PoC Documentation Template below.

---

PoC Documentation Template

# PoC: [Technology/Approach Name]

**Date**: 2026-01-10
**Author**: [Your Name]
**Duration**: [X days]

---

## Problem Statement

[What problem are we trying to solve?]

**Current situation:**
[What we do now]

**Desired outcome:**
[What we want to achieve]

---

## Success Criteria

| Criterion | Target | Result | Status |
|-----------|--------|--------|--------|
| [Criterion 1] | [Target] | [Actual] | ✅/❌ |
| [Criterion 2] | [Target] | [Actual] | ✅/❌ |
| [Criterion 3] | [Target] | [Actual] | ✅/❌ |

---

## Approach Evaluated

**Technology/Framework**: [Name and version]

**Why this approach?**
[Brief rationale]

**Key features tested:**
1. [Feature 1]
2. [Feature 2]
3. [Feature 3]

---

## Implementation Summary

**What was built:**
[Brief description of what you implemented]

**Architecture:**
[Simple diagram or description]

**Key code:**
[Link to repo or key snippets]

---

## Results

### What Worked ✅

- [Thing 1 that worked well]
- [Thing 2 that worked well]
- [Thing 3 that worked well]

### What Didn't Work ❌

- [Challenge 1]
- [Challenge 2]
- [Challenge 3]

### What Surprised Us 🔍

- [Unexpected finding 1]
- [Unexpected finding 2]

### Performance Metrics

| Metric | Target | Actual | Status |
|--------|--------|--------|--------|
| Response time | < 100ms | 85ms | ✅ |
| Memory usage | < 500MB | 320MB | ✅ |
| Throughput | > 1000/s | 850/s | ⚠️ |

---

## Recommendation

**Decision**: ✅ Proceed / ⚠️ Proceed with conditions / ❌ Do not proceed

**Rationale**:
[Why this recommendation?]

**Risks & Mitigations**:
- **Risk 1**: [Description]
  - **Mitigation**: [How to handle it]
- **Risk 2**: [Description]
  - **Mitigation**: [How to handle it]

**Conditions** (if applicable):
- [Condition 1]
- [Condition 2]

---

## Follow-Up Work

**If we proceed, next steps:**

1. [Step 1]
2. [Step 2]
3. [Step 3]

**Estimated effort**: [Time/complexity estimate]

**Open questions:**
- [Question 1]
- [Question 2]

---

## References

- [Documentation link]
- [Example project link]
- [Related research]
- [PoC repository]

---

## Appendix

### Setup Instructions

```bash
# How to run this PoC

Key Code Snippets

// Important code examples

Screenshots/Diagrams

[If applicable]

---

## PoC Examples

### Example 1: Technology Evaluation

**Scenario**: Evaluating Elasticsearch vs Typesense for product search

**Success Criteria:**
1. Query response time < 100ms for 10k products
2. Relevance: Top 5 results are relevant
3. Setup time < 4 hours
4. Can integrate with existing Node.js API

**Time Budget**: 3 days (1.5 days per option)

**What to Test:**

**Elasticsearch PoC:**
```javascript
// poc-elasticsearch/
// - Setup Elasticsearch locally (Docker)
// - Index 10k sample products
// - Implement basic search endpoint
// - Benchmark query performance
// - Test relevance with sample queries

Typesense PoC:

// poc-typesense/
// - Setup Typesense Cloud (faster)
// - Index same 10k products
// - Implement same search endpoint
// - Benchmark query performance
// - Test relevance with same queries

Evaluation Matrix:

Criterion	Weight	Elasticsearch	Typesense
Query speed	HIGH	⚠️ 120ms	✅ 65ms
Relevance	HIGH	✅ 9/10	✅ 8/10
Setup time	MED	❌ 6 hours	✅ 2 hours
Integration	HIGH	✅ Easy	✅ Easy
Cost	MED	⚠️ Self-hosted	✅ $29/mo

Recommendation: Proceed with Typesense

• Faster queries
• Much easier setup
• Good enough relevance
• Lower operational overhead

---

Example 2: Integration Validation

Scenario: Can we integrate Auth0 with our existing Laravel app?

Success Criteria:

1. Users can log in via Auth0
2. Existing user data migrates cleanly
3. Session handling works with our architecture
4. Integration takes < 2 days

Time Budget: 2 days

What to Test:

// poc-auth0-integration/
// Day 1:
// - Setup Auth0 tenant
// - Integrate Auth0 PHP SDK
// - Implement login flow
// - Test with sample users

// Day 2:
// - Migrate 100 sample users
// - Test session handling
// - Verify existing middleware compatibility
// - Document integration steps

Results:

• ✅ Login flow works seamlessly
• ✅ User migration script successful
• ❌ Session handling conflicts with existing Redis setup
  • Mitigation: Need to refactor session middleware (1-2 days)
• ✅ Integration complexity acceptable

Recommendation: Proceed with conditions

• Add 2 days for session refactoring
• Plan user migration strategy
• Test with staging environment first

---

Example 3: Performance Validation

Scenario: Can we use WebSockets for real-time updates instead of polling?

Success Criteria:

1. Handle 1000 concurrent connections
2. Message latency < 50ms
3. Memory usage < 500MB
4. Reliable reconnection on network issues

Time Budget: 3 days

What to Test:

// poc-websockets/
// Day 1:
// - Setup Socket.io server
// - Implement basic pub/sub
// - Test with 10 concurrent clients

// Day 2:
// - Load test with 1000 connections
// - Measure memory and CPU
// - Test reconnection logic

// Day 3:
// - Integrate with existing API
// - Test authentication flow
// - Document findings

Load Test Results:

# Test with 1000 concurrent connections
Connections: 1000
Messages/sec: 5000
Avg latency: 42ms ✅
Memory usage: 380MB ✅
CPU usage: 45% ⚠️

Findings:

• ✅ Meets all performance criteria
• ⚠️ Higher CPU usage than expected (needs monitoring)
• ✅ Reconnection works reliably
• ✅ 10x reduction in server requests vs polling

Recommendation: Proceed

• Significant performance improvement
• CPU usage acceptable for our infrastructure
• Consider horizontal scaling if needed

---

Example 4: Architecture Pattern Validation

Scenario: Should we adopt Event Sourcing for our order system?

Success Criteria:

1. Can model order lifecycle as events
2. Can reconstruct state from events
3. Query performance acceptable
4. Team can understand the pattern

Time Budget: 4 days

What to Test:

// poc-event-sourcing/
// Day 1-2:
// - Model order events (OrderPlaced, OrderPaid, etc.)
// - Implement event store (simple file-based)
// - Build event replay mechanism

// Day 3:
// - Build read model (projection)
// - Test query performance
// - Compare to current approach

// Day 4:
// - Team review session
// - Document trade-offs

Events Modeled:

OrderPlaced → OrderPaid → OrderShipped → OrderDelivered

Findings:

• ✅ Event model is clean and expressive
• ✅ Event replay works correctly
• ⚠️ Query performance slower than current (200ms vs 50ms)
  • Requires optimized projections
• ❌ Team finds pattern complex (3-hour learning curve)

Trade-offs:

Aspect	Current (CRUD)	Event Sourcing
Simplicity	✅ Very simple	❌ Complex
Audit trail	❌ Limited	✅ Complete
Query speed	✅ Fast	⚠️ Slower
Debugging	✅ Easy	⚠️ Harder
Flexibility	⚠️ Limited	✅ High

Recommendation: Do not proceed (for now)

• Complexity outweighs benefits for our use case
• Team learning curve too steep
• Current audit logging is sufficient
• Revisit if audit requirements change

---

PoC Anti-Patterns

1. Scope Creep

❌ Anti-pattern: Adding features beyond validation criteria

Signs:

• "While we're at it, let's add..."
• PoC takes 2+ weeks
• Building "production-quality" code
• Adding features for completeness

Example:

Initial: "Test if GraphQL reduces payload size"
Scope creep:
  → Add authentication
  → Add caching layer
  → Add comprehensive error handling
  → Add monitoring
  → Add documentation site

Fix:

• Write success criteria upfront
• Stick to the criteria ruthlessly
• Say "no" to nice-to-haves
• Time-box the work

---

2. Production-izing the PoC

❌ Anti-pattern: Using PoC code in production

Signs:

• "The PoC works, let's just ship it"
• Refactoring PoC code for months
• Building on technical debt
• Security vulnerabilities

Why it's bad:

• PoC code lacks error handling
• No tests or monitoring
• Security not considered
• Performance not optimized

Fix:

• Treat PoC as throwaway
• Use PoC to inform new implementation
• Budget time for proper development
• Don't let time pressure force shortcuts

Proper Approach:

PoC (3 days) → Decision (1 day) → Implementation (2 weeks)

---

3. Skipping Documentation

❌ Anti-pattern: Not documenting PoC findings

Signs:

• "I'll document it later"
• Team doesn't know what was learned
• Repeat same PoC months later
• No record of decision rationale

Fix:

• Document as you go
• Use the PoC template
• Share findings with team
• Record the decision (see ADR skill)

---

4. No Success Criteria

❌ Anti-pattern: Starting PoC without clear goals

Signs:

• "Let's just try it and see"
• No clear end state
• Can't decide if PoC succeeded
• Endless tinkering

Example:

Bad:  "Let's try Redis"
Good: "Can Redis reduce our API response time from 200ms to <100ms?"

Fix:

• Define success criteria before starting
• Make criteria measurable
• Get stakeholder agreement
• Use criteria to guide work

---

5. Ignoring Negative Results

❌ Anti-pattern: Continuing despite PoC failure

Signs:

• "It didn't work, but let's try longer"
• Moving goalposts when criteria aren't met
• Sunk cost fallacy
• Ignoring evidence

Example:

Success Criteria: "Query time < 100ms"
Actual Result: 300ms consistently
Wrong: "Let's optimize it more"
Right: "This doesn't meet our needs, try alternative"

Fix:

• Accept negative results as valuable
• PoC that says "no" is successful
• Document why it didn't work
• Move on to alternatives

Remember: A PoC that says "don't do this" is just as valuable as one that says "do this."

---

PoC Checklist

Before Starting

• Success criteria clearly defined
• Key risks identified
• Time budget set (< 5 days)
• Scope determined (what to include/exclude)
• Research completed (docs, examples)
• Stakeholders aligned on goals

During PoC

• Staying within time budget
• Focusing on success criteria
• Documenting findings as you go
• Testing with realistic data
• Avoiding scope creep
• Not over-engineering

After PoC

• All success criteria evaluated
• Results documented
• Recommendation made (go/no-go)
• Risks and mitigations identified
• Follow-up work estimated
• Decision shared with team
• PoC code archived/deleted

---

Integration with Other Skills

With Technical Research

• Use research skill to identify candidates
• Use PoC to validate top choices
• Combine research + PoC for decisions

Workflow:

Research (identify 3 options)
  → PoC (validate top 2)
  → Decision

With Architecture Review

• Use PoC to validate architecture decisions
• Test integration points before committing
• Validate performance assumptions

With Technical Lead Role

• Use PoCs to de-risk technical decisions
• Demonstrate feasibility to stakeholders
• Guide team toward evidence-based decisions

With Evaluation Skill

• Evaluation provides criteria
• PoC provides hands-on validation
• Together they inform decisions

---

Quick Reference

PoC Time Budgets

Scope	Time
Simple integration	1-2 days
Technology evaluation	2-3 days
Complex integration	3-5 days
Architecture pattern	3-5 days

PoC Phases

1. Research (20%) - Read docs, find examples
2. Setup (10%) - Get to "Hello World"
3. Implementation (50%) - Build core feature
4. Testing (15%) - Validate criteria
5. Documentation (5%) - Capture learnings

Success Criteria Template

## Success Criteria
1. [Functional requirement - does it work?]
2. [Performance requirement - is it fast enough?]
3. [Integration requirement - does it fit?]
4. [Team requirement - can we use it?]

PoC vs Production

Aspect	PoC	Production
Error handling	Minimal	Comprehensive
Testing	Manual only	Automated suite
Performance	Good enough	Optimized
Security	Basic	Hardened
Documentation	Notes	Complete
Monitoring	None	Full observability
Code quality	Working	Maintainable

---

Remember: The goal of a PoC is to learn and decide, not to ship. Build the minimum to answer your question, document your findings, and make an informed decision. Good PoCs save weeks of wasted effort by catching problems early.