Spike

Structured technical investigation to reduce uncertainty. Answer specific questions, not “explore X.”

Integrates with:

• ohno — Creates spike task, tracks time-box, logs findings
• project-harness — Works within session workflow
• All domain skills — May invoke for specialized investigation

Core Philosophy

┌─────────────────────────────────────────────────────────────────┐
│                   SPIKE = BOUNDED UNCERTAINTY                    │
├─────────────────────────────────────────────────────────────────┤
│  INPUT: Vague concern or unknown → "Can we use GraphQL?"        │
│  OUTPUT: Decision + evidence    → "Yes, with caveats. Here's    │
│                                    the proof-of-concept."       │
├─────────────────────────────────────────────────────────────────┤
│  TIME-BOXED: 2-4 hours default, never >1 day                    │
│  QUESTION-FOCUSED: Answer ONE specific question                 │
│  OUTPUT-DRIVEN: End with decision, not more questions           │
│  DOCUMENTED: Learnings captured even if answer is "no"          │
└─────────────────────────────────────────────────────────────────┘

Quick Start

1. Frame the Question

Transform vague concerns into spike-able questions:

Good spike questions have:

• A yes/no or A/B answer
• Measurable success criteria
• Clear scope boundaries

2. Define Time Box & Success Criteria

## Spike Definition

**Question**: Can we use Cloudflare D1 for our multi-tenant data model?

**Time Box**: 3 hours
**Type**: Feasibility

**Success Criteria**:
- [ ] Row-level security works for tenant isolation
- [ ] Query performance acceptable (<50ms for typical queries)
- [ ] Migration path from current PostgreSQL clear

**Out of Scope**:
- Full migration implementation
- Performance tuning
- Production deployment

3. Create Spike Task in ohno

# Create spike task
ohno add "Spike: D1 multi-tenant feasibility" --type spike --estimate 3h

# Or via MCP
create_task({
  title: "Spike: D1 multi-tenant feasibility",
  type: "spike",
  estimate: "3h",
  tags: ["spike", "feasibility", "database"]
})

4. Investigate (with checkpoints)

START → 25% checkpoint → 50% checkpoint → 75% checkpoint → CONCLUDE
 │           │                │                │              │
 │           │                │                │              └─ Write report
 │           │                │                └─ Evaluate findings
 │           │                └─ Check: On track? Pivot needed?
 │           └─ Initial findings assessment
 └─ Begin investigation

50% Checkpoint (critical):

## Spike Checkpoint: 1.5h of 3h elapsed

**Progress**: 
- [x] Set up D1 database
- [x] Created test tenant structure
- [ ] Performance benchmarks
- [ ] Migration path analysis

**On Track?**: Yes / No / Pivoting
**Blockers**: None
**Adjustment**: [if any]

5. Conclude with Decision

Every spike ends with ONE of:

• GO: Proceed with approach, create implementation tasks
• NO-GO: Don’t proceed, document why
• PIVOT: Different approach needed, create new spike
• MORE-INFO: Specific additional info needed (rare, max 1 re-spike)

Spike Types

See references/spike-types.md for detailed type-specific guidance.

Spike Report Format

Generate report in .claude/spikes/ folder:

# Spike Report: [Title]

**Date**: 2026-01-18
**Duration**: 2.5h (of 3h budget)
**Type**: Feasibility
**Decision**: GO ✓ | NO-GO ✗ | PIVOT ↺ | MORE-INFO ?

## Question
Can we use Cloudflare D1 for multi-tenant data model with row-level security?

## Answer
**YES** — D1 supports row-level filtering, performance is acceptable for our scale.

## Evidence

### What Worked
- Created test database with 3 tenants, 10k rows each
- Queries with tenant_id filter: 15-30ms average
- No cross-tenant data leakage in security tests

### What Didn't Work
- Bulk inserts >1000 rows timeout (need batching)
- No native RLS — must enforce in application layer

### Proof of Concept
Location: `/spikes/d1-multi-tenant/`
\```typescript
// Key pattern: tenant isolation
const getData = async (tenantId: string) => {
  return db.prepare(
    "SELECT * FROM data WHERE tenant_id = ?"
  ).bind(tenantId).all();
};
\```

## Recommendation
Proceed with D1. Application-layer tenant isolation is acceptable given our controlled access patterns.

## Follow-up Tasks
1. [ ] Design tenant isolation middleware
2. [ ] Create migration script from PostgreSQL
3. [ ] Set up batch insert utility for bulk operations

## Time Log
- 0:30 - Environment setup, D1 database creation
- 1:00 - Schema design, test data generation
- 1:30 - Query performance testing
- 2:00 - Security boundary testing
- 2:30 - Documentation and report

ohno Integration

Creating Spike Tasks

Spikes are tasks with type: spike:

# CLI
ohno add "Spike: [question]" --type spike --estimate 3h --tags spike,feasibility

# After completion
ohno done <spike-id> --notes "GO - see .claude/spikes/spike-name.md"

Creating Follow-up Tasks

After spike concludes, create implementation tasks:

# From spike findings
ohno add "Design tenant isolation middleware" --parent <epic-id> --tags d1,security
ohno add "Create PostgreSQL to D1 migration script" --parent <epic-id>
ohno add "Implement batch insert utility" --parent <epic-id>

Spike Task States

planned → in_progress → done (with decision)
                     └→ blocked (if external dependency)

Anti-Patterns

During Definition

During Investigation

At Conclusion

Workflow Protocol

Starting a Spike

## Spike Start Checklist

1. [ ] Question clearly framed (yes/no or A/B answer)
2. [ ] Success criteria defined (measurable)
3. [ ] Time box set (default 2-4h, max 1 day)
4. [ ] Spike type identified
5. [ ] Spike task created in ohno
6. [ ] Out-of-scope boundaries documented

During Investigation

## Investigation Log

### Checkpoint 1 (25%)
- [Initial findings]
- [Blockers/surprises]

### Checkpoint 2 (50%) — DECISION POINT
- [Progress assessment]
- [On track? Pivot needed?]
- [Adjusted approach if any]

### Checkpoint 3 (75%)
- [Near-final findings]
- [Start forming decision]

Concluding a Spike

## Spike End Checklist

1. [ ] Decision made: GO / NO-GO / PIVOT / MORE-INFO
2. [ ] Evidence documented
3. [ ] Spike report written to `.claude/spikes/`
4. [ ] Proof-of-concept code saved (if applicable)
5. [ ] Follow-up tasks created in ohno
6. [ ] Spike task marked done with decision notes
7. [ ] Knowledge shared (not just filed away)

Decision Framework

When to GO

• Success criteria met
• Risks acceptable and mitigatable
• Clear implementation path
• Performance/feasibility confirmed

When to NO-GO

• Fundamental blockers discovered
• Performance requirements unachievable
• Complexity too high for value
• Better alternatives identified

When to PIVOT

• Original approach won’t work
• New approach emerged during investigation
• Scope needs significant adjustment

When to MORE-INFO (use sparingly)

• Specific, bounded additional info needed
• Can be obtained in ≤2h additional work
• NOT “let’s investigate more”

Question Framing Guide

Transform vague concerns into spike-able questions:

See references/question-patterns.md for comprehensive examples.

Output Location

All spike outputs go to .claude/spikes/:

.claude/
├── spikes/
│   ├── d1-multi-tenant-2026-01-18.md    ← Spike report
│   └── d1-multi-tenant/                  ← Proof-of-concept code
├── PROJECT.md
└── tasks.db

References

• references/spike-types.md — Detailed guidance per spike type
• references/question-patterns.md — Question framing techniques
• references/output-templates.md — Report templates