--- name: spike description: Time-boxed technical investigation with structured output. Use for feasibility studies, architecture exploration, integration assessment, performance analysis, or risk evaluation. Creates spike tasks in ohno, enforces time-boxing, generates spike reports, and creates actionable follow-up tasks. Triggers on "spike on X", "investigate whether we can", "how hard would it be to", "what's the best approach for", or any exploratory technical question needing bounded research. --- # 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: | Vague | Spike Question | |-------|----------------| | "Look into caching" | "Can Redis reduce our API latency to <100ms for user lookups?" | | "Explore auth options" | "Can we use OAuth2 with Google for our auth flow?" | | "Check if X is possible" | "Can library X handle 10k concurrent connections?" | **Good spike questions have:** - A yes/no or A/B answer - Measurable success criteria - Clear scope boundaries ### 2. Define Time Box & Success Criteria ```markdown ## 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 ```bash # 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):** ```markdown ## 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 | Type | Purpose | Typical Duration | Output | |------|---------|------------------|--------| | **Feasibility** | Can we do X? | 2-4h | Yes/no + proof | | **Architecture** | How should we structure X? | 3-6h | Design decision | | **Integration** | How connect to service X? | 2-4h | Working connection | | **Performance** | Can X meet requirements? | 2-4h | Benchmarks | | **Risk** | What could go wrong? | 2-4h | Risk register | See [references/spike-types.md](references/spike-types.md) for detailed type-specific guidance. --- ## Spike Report Format Generate report in `.claude/spikes/` folder: ```markdown # 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`: ```bash # CLI ohno add "Spike: [question]" --type spike --estimate 3h --tags spike,feasibility # After completion ohno done --notes "GO - see .claude/spikes/spike-name.md" ``` ### Creating Follow-up Tasks After spike concludes, create implementation tasks: ```bash # From spike findings ohno add "Design tenant isolation middleware" --parent --tags d1,security ohno add "Create PostgreSQL to D1 migration script" --parent ohno add "Implement batch insert utility" --parent ``` ### Spike Task States ``` planned → in_progress → done (with decision) └→ blocked (if external dependency) ``` --- ## Anti-Patterns ### During Definition | Anti-Pattern | Example | Fix | |--------------|---------|-----| | Vague question | "Investigate caching" | "Can Redis reduce latency to <100ms?" | | No success criteria | "See if it works" | Define measurable outcomes | | Unbounded scope | "Explore all options" | Pick ONE option to test | | Too long | "1 week spike" | Max 1 day, usually 2-4h | ### During Investigation | Anti-Pattern | Example | Fix | |--------------|---------|-----| | Scope creep | "While I'm here, let me also..." | Stay on question | | Rabbit holes | Deep-diving tangent | 50% checkpoint catches this | | Building too much | Full implementation | Proof-of-concept only | | No checkpoints | Realize late you're stuck | Check at 25%, 50%, 75% | ### At Conclusion | Anti-Pattern | Example | Fix | |--------------|---------|-----| | No decision | "It depends" | Force GO/NO-GO/PIVOT | | No documentation | Knowledge lost | Write spike report | | Vague follow-ups | "Continue investigating" | Specific actionable tasks | | Re-spike loop | Endless "more info needed" | Max 1 re-spike, then decide | --- ## Workflow Protocol ### Starting a Spike ```markdown ## 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 ```markdown ## 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 ```markdown ## 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: | Concern Type | Vague Version | Spike Question | |--------------|---------------|----------------| | Feasibility | "Can we use X?" | "Can X handle [specific requirement] within [constraint]?" | | Performance | "Is it fast enough?" | "Can X achieve <[target]ms for [operation]?" | | Integration | "Will it work with Y?" | "Can X connect to Y using [method] with [auth]?" | | Architecture | "How should we build it?" | "Should we use A or B for [specific aspect]?" | | Risk | "What could go wrong?" | "What are the top 3 failure modes of X?" | See [references/question-patterns.md](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](references/spike-types.md) — Detailed guidance per spike type - [references/question-patterns.md](references/question-patterns.md) — Question framing techniques - [references/output-templates.md](references/output-templates.md) — Report templates