moicle 2.0.0 → 2.2.0

package/assets/skills/research/spike/SKILL.md

@@ -3,514 +3,206 @@ name: research-spike
 description: Spike/Research workflow for exploring unknowns before committing to implementation. Use when researching, prototyping, doing proof of concept, or when user says "spike", "research", "prototype", "poc", "explore", "investigate".
 ---
 
-# Spike/Research Workflow
+# Spike / Research Workflow
 
-Time-boxed exploration workflow for investigating unknowns, validating assumptions, and de-risking decisions before committing to full implementation.
+Time-boxed exploration to de-risk a decision by **building** (not just reading). Produces a recommendation + ADR, not production code.
 
 ## When to use this skill
 
-- ✅ Need to validate a technical assumption by building (not just reading)
-- ✅ Picking between 2+ technical options and need real comparison
-- ✅ De-risking a critical path before committing to it
-- ❌ Want to compare options via docs / SO / blogs only → use `/research:web`
+- ✅ Need to validate a technical assumption by building
+- ✅ Picking between 2+ options and need real comparison
+- ✅ De-risking a critical path before committing
+- ❌ Want to compare options via docs only → use `/research:web`
 - ❌ Already decided on the approach → use `/feature:new`
 - ❌ Stuck on a known bug → use `/fix:root-cause`
 
 ## Read Architecture First
 
-Read `ddd-architecture.md` + stack-specific doc to understand current patterns before exploring alternatives.
+Detect stack via `~/.claude/architecture/_shared/stack-detection.md`. Skim stack doc to understand current patterns — the spike output should fit the architecture or explicitly say why it doesn't.
 
-## Workflow Overview
+---
+
+## Workflow
 
 ```
-┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐
-│ 1. DEFINE│──▶│2. RESEARCH──▶│3. PROTOTYPE──▶│4. EVALUATE│
-└──────────┘   └──────────┘   └──────────┘   └──────────┘
-     │                                              │
-     │          Timebox Expired?                    │
-     └──────────────────────────────────────────────┘
-                    End & Document
+DEFINE → RESEARCH → PROTOTYPE → EVALUATE
+   ↑                                  │
+   └────── timebox expired ───────────┘
 ```
 
 ---
 
-## Phase 1: DEFINE
-
-**Goal**: Define the question/problem to research and set timebox
-
-### Actions
-1. Clarify what's unknown:
-   - What decision needs to be made?
-   - What assumptions need validation?
-   - What technical unknowns exist?
+## Phase 1: DEFINE (15-30 min — never skip)
 
-2. **Identify project stack and read architecture doc**
+**Goal:** lock the question, success criteria, timebox. Without these the spike has no exit condition.
 
-3. Define research question:
-   ```
-   Good: "Can we integrate Auth0 with our React app without breaking Clean Architecture?"
-   Bad: "Research authentication"
-   ```
+### Spike brief
 
-4. Set timebox based on spike type:
-   - Quick spike: 2-4 hours
-   - Medium spike: 1-2 days
-   - Deep spike: 3-5 days
-   - **Never exceed 1 week**
-
-5. Define success criteria:
-   ```
-   Spike is successful when we know:
-   - [ ] Criterion 1
-   - [ ] Criterion 2
-   - [ ] Criterion 3
-   ```
-
-### Output
 ```markdown
-## Spike: [Name]
+## Spike: {short name}
 
-### Type
-[Technical/Design/Functional]
+### Question
+{ONE specific question — answerable yes/no or "pick A vs B vs C"}
 
-### Stack & Architecture
-- Stack: [Flutter/React/Go/Laravel/Remix]
-- Architecture Doc: [path to architecture file]
+### Why now
+{What decision blocks on this answer? When is the decision needed?}
 
-### Research Question
-[Clear, specific question]
+### Options on the table
+- Option A: {name + 1 line}
+- Option B: {name + 1 line}
+- (Option C: only if relevant)
 
-### Why This Spike
-[Why we need this research before implementing]
+### Success criteria
+- [ ] {Specific, observable — e.g., "P95 latency <50ms at 1k req/s"}
+- [ ] {e.g., "Integration with X library compiles + 1 test passes"}
+- [ ] {e.g., "Estimated migration effort ≤2 sprints"}
 
 ### Timebox
-- Duration: [X hours/days]
-- Start: [timestamp]
-- End: [timestamp]
-
-### Success Criteria
-We will know enough when:
-- [ ] Criterion 1
-- [ ] Criterion 2
-- [ ] Criterion 3
-
-### Out of Scope
-[What we're NOT exploring]
+- Quick spike: 2-4 hours
+- Standard: 1-2 days
+- Deep spike: 3-5 days (rare — usually means scope is too big)
+
+### Red flags (stop early if hit)
+- Scope creep into productionising
+- Option requires breaking architecture rules
+- Two options become "obviously the same" after 1 hour
 ```
 
 ### Gate
-- [ ] Research question clear and specific
-- [ ] Architecture doc identified
-- [ ] Timebox set (≤ 1 week)
-- [ ] Success criteria defined
-- [ ] Out of scope defined
+- [ ] Question is ONE specific question
+- [ ] Success criteria are observable (not "feels right")
+- [ ] Timebox + red flags written
+- [ ] User CONFIRMED brief before starting
 
 ---
 
-## Phase 2: RESEARCH
-
-**Goal**: Gather information and explore options
+## Phase 2: RESEARCH (≤25% of timebox)
 
-### Actions
-1. **Read relevant architecture docs** for context
+**Goal:** know enough to prototype intelligently, don't over-read.
 
-2. Research approaches:
-   - [ ] Read documentation/specs
-   - [ ] Survey existing solutions
-   - [ ] Check community best practices
-   - [ ] Review similar projects
-   - [ ] Consult with team/experts
+Run `/research:web` for the topic if you haven't already. Capture:
 
-3. Evaluate against architecture:
-   - Does it fit our patterns?
-   - Which layers would it affect?
-   - Does it respect boundaries?
-   - What's the integration complexity?
+- Official docs URLs (read, don't just bookmark)
+- Known gotchas / GitHub issues for each option
+- Prior art: anyone tried this combo? what was their conclusion?
+- Constraints from existing stack (versions, license, infra)
 
-4. Document findings in real-time:
-   ```markdown
-   ## Research Log
-
-   ### [Timestamp] - Option 1: [Name]
-   **Source**: [link/person]
-   **Pros**:
-   - Pro 1
-   - Pro 2
-
-   **Cons**:
-   - Con 1
-   - Con 2
-
-   **Architecture Fit**: [Good/Moderate/Poor]
-   - [Notes on how it fits our architecture]
+### Gate
+- [ ] At least 2 sources per option
+- [ ] Known gotchas listed
+- [ ] Constraints documented
 
-   ### [Timestamp] - Option 2: [Name]
-   ...
-   ```
+---
 
-5. Track time spent vs timebox
+## Phase 3: PROTOTYPE (the bulk of the timebox)
 
-### Research Output
-```markdown
-## Research Findings
-
-### Options Explored
-1. **Option 1**: [brief description]
-   - Architecture fit: [assessment]
-   - Complexity: [Low/Medium/High]
-   - Risk: [Low/Medium/High]
-
-2. **Option 2**: [brief description]
-   - Architecture fit: [assessment]
-   - Complexity: [Low/Medium/High]
-   - Risk: [Low/Medium/High]
-
-### Architecture Impact
-**Affected Layers**: [list from architecture doc]
-**Pattern Changes**: [any changes to current patterns]
-**Dependencies**: [new dependencies needed]
-
-### Initial Recommendation
-[Which option looks most promising and why]
-```
+**Goal:** build the smallest thing that answers the question.
 
-### Gate
-- [ ] Multiple options explored (at least 2-3)
-- [ ] Architecture impact assessed
-- [ ] Pros/cons documented
-- [ ] Still within timebox
+### Rules
+- **Quick and dirty** — no tests beyond what's needed to verify the question
+- **One option at a time** — full prototype for A, then full prototype for B
+- **In a sandbox** — separate branch, never merge to main
+- **Time-stamped commits** — `spike: A reaches 1k req/s with sync handler` so the timeline is reviewable
+- **Stop on red flag** — if scope creeps or hits a wall, do not push through
 
----
+### What "smallest" means
+- Skip auth, skip error handling, skip pagination
+- Hardcode config that you'd normally pull from env
+- Stub anything not under test
+- 1-2 happy-path scenarios is enough to verify success criteria
 
-## Phase 3: PROTOTYPE
-
-**Goal**: Build quick proof of concept to validate approach
-
-### Principles
-1. **Quick & Dirty** - Don't worry about code quality
-2. **Focused** - Prove one thing only
-3. **Throwaway** - Code will likely be discarded
-4. **Time-boxed** - Stop when time is up
-
-### Actions
-1. **Read architecture doc** for the affected areas
-
-2. Set prototype scope:
-   ```markdown
-   ## Prototype Scope
-   **Proving**: [the one thing we're validating]
-   **NOT proving**: [everything else]
-   **Time**: [X hours from total timebox]
-   ```
-
-3. Build minimal POC:
-   - Create in separate branch/directory
-   - Follow architecture patterns where reasonable
-   - Mark as prototype:
-     ```
-     // PROTOTYPE - NOT PRODUCTION CODE
-     // Spike: [spike name]
-     ```
-
-4. Test the critical path only:
-   - Does it work?
-   - Does it integrate?
-   - Are there blockers?
-
-5. Document observations:
-   ```markdown
-   ## Prototype Observations
-
-   ### What Worked
-   - [observation 1]
-   - [observation 2]
-
-   ### What Didn't Work
-   - [issue 1]
-   - [issue 2]
-
-   ### Surprises
-   - [unexpected finding 1]
-   - [unexpected finding 2]
-
-   ### Blockers Found
-   - [blocker 1]
-   - [blocker 2]
-   ```
-
-### Prototype Output
-```markdown
-## Prototype Results
-
-### Implementation
-- Branch/Location: [path]
-- Time Spent: [X hours]
-- Status: [Working/Partially Working/Not Working]
-
-### Key Learnings
-1. [learning 1]
-2. [learning 2]
-3. [learning 3]
-
-### Architecture Compliance
-- Fits patterns: [Yes/No/Partially]
-- Issues found: [list]
-- Workarounds needed: [list]
-
-### Effort Estimate (if proceeding)
-- [Rough T-shirt size: XS/S/M/L/XL]
-- [Based on: what you learned]
-```
+### Stop early when
+- All success criteria met for one option (don't gold-plate)
+- All options fail the same criterion (pivot the question)
+- Timebox 75% used and not converging (something's wrong — stop, regroup)
 
 ### Gate
-- [ ] Prototype proves/disproves key assumption
-- [ ] Blockers identified
-- [ ] Effort estimated
-- [ ] Still within timebox (if not, stop and document)
+- [ ] Each option prototyped to the point of answering the question
+- [ ] Success criteria measured (numbers, not vibes)
+- [ ] Findings captured in spike branch commits
 
 ---
 
 ## Phase 4: EVALUATE
 
-**Goal**: Assess results and make recommendation
-
-### Actions
-1. **Review findings against architecture doc**
-
-2. Assess each option:
-   ```markdown
-   ## Option Assessment
-
-   ### Option 1: [Name]
-   **Architecture Fit**: ⭐⭐⭐⭐⭐ (5/5)
-   - [why it fits/doesn't fit]
-
-   **Complexity**: ⭐⭐⭐ (3/5)
-   - [complexity assessment]
-
-   **Risk**: ⭐⭐ (2/5 - lower is better)
-   - [risk assessment]
-
-   **Effort**: [T-shirt size]
-   - [effort justification]
-
-   **Prototype Result**: [Successful/Partial/Failed]
-   ```
-
-3. Make recommendation:
-   ```markdown
-   ## Recommendation
+**Goal:** turn the prototype into a recommendation + ADR.
 
-   ### Choice: [Option X]
+### Comparison matrix
 
-   ### Reasoning
-   1. [reason 1]
-   2. [reason 2]
-   3. [reason 3]
+| Criterion | Option A | Option B | Notes |
+|-----------|----------|----------|-------|
+| Success criterion 1 (e.g., latency) | 42ms ✅ | 87ms ❌ | A at 1k rps, B saturates earlier |
+| Success criterion 2 (e.g., effort) | 1 sprint | 3 sprints | B requires new dependency |
+| Fit with architecture | ✅ | ⚠️ Requires port redesign | |
+| Risk | low | medium | B unknowns: lib maturity, no LTS |
+| Team familiarity | high | low | |
 
-   ### Trade-offs Accepted
-   - [trade-off 1]
-   - [trade-off 2]
+### ADR template
 
-   ### Risks & Mitigations
-   - Risk: [risk 1]
-     Mitigation: [how to mitigate]
-   - Risk: [risk 2]
-     Mitigation: [how to mitigate]
-
-   ### Implementation Plan (High-Level)
-   1. [phase 1]
-   2. [phase 2]
-   3. [phase 3]
-
-   ### Next Steps
-   - [ ] Next step 1
-   - [ ] Next step 2
-   - [ ] Next step 3
-   ```
-
-4. Create decision record:
-   ```markdown
-   # ADR: [Decision Title]
-
-   Date: [date]
-   Status: Proposed
-
-   ## Context
-   [What led to this spike]
-
-   ## Decision
-   [What we decided]
-
-   ## Consequences
-   - Positive: [list]
-   - Negative: [list]
-   - Neutral: [list]
-
-   ## Alternatives Considered
-   - Option A: [brief + why rejected]
-   - Option B: [brief + why rejected]
-   ```
-
-### Final Deliverable
 ```markdown
-## Spike Summary: [Name]
-
-**Duration**: [actual time spent] / [timebox]
-**Date**: [start] - [end]
-**Stack**: [stack]
-**Researcher**: [name/team]
+# ADR-NNN: {Decision title}
 
-### Question Answered
-[Original research question]
-
-### Answer
-[Clear answer based on findings]
-
-### Recommendation
-[Clear recommendation with reasoning]
+## Status
+Accepted / Superseded / Deprecated
 
-### Supporting Evidence
-- Research: [key findings]
-- Prototype: [what we built and learned]
-- Architecture: [how it fits]
+## Context
+{What problem we faced, what alternatives we considered}
 
-### Confidence Level
-[High/Medium/Low] - [why]
+## Decision
+{The chosen option}
 
-### Next Actions
-1. [ ] Action 1
-2. [ ] Action 2
-3. [ ] Action 3
+## Consequences
+**Positive:** {gains}
+**Negative:** {tradeoffs / debt taken on}
 
-### Artifacts
-- Research notes: [link]
-- Prototype code: [link/path]
-- Decision record: [link]
+## Spike evidence
+{Link to spike branch + key benchmark numbers}
 ```
 
-### Gate
-- [ ] Recommendation clear and justified
-- [ ] Risks identified and mitigated
-- [ ] Decision record created
-- [ ] Prototype cleaned up or archived
-- [ ] Findings documented
-
----
+### Cleanup
+- [ ] Spike branch tagged (`spike/{name}-{date}`) so it can be referenced
+- [ ] Spike code NOT merged — production should re-implement properly via `/feature:new`
+- [ ] ADR committed to `docs/adr/` (or equivalent)
 
-## Quick Reference
-
-### Architecture Docs
-| Stack | Doc |
-|-------|-----|
-| All | `clean-architecture.md` |
-| Flutter | `flutter-mobile.md` |
-| React | `react-frontend.md` |
-| Go | `go-backend.md` |
-| Laravel | `laravel-backend.md` |
-| Remix | `remix-fullstack.md` |
-| Monorepo | `monorepo.md` |
-
-### Spike Types
-
-| Type | Purpose | Example |
-|------|---------|---------|
-| **Technical** | Validate technical feasibility | Can we use WebSockets with our architecture? |
-| **Design** | Explore design options | What's the best state management for this feature? |
-| **Functional** | Understand requirements | How should offline sync work? |
-
-### Timebox Guidelines
-
-| Complexity | Timebox | Output |
-|------------|---------|--------|
-| Quick | 2-4 hours | Research + decision |
-| Medium | 1-2 days | Research + small POC + decision |
-| Deep | 3-5 days | Research + full POC + ADR |
-| **Max** | **1 week** | **Stop and reassess** |
-
-### When to Stop Early
-- ✅ Success criteria met early
-- ✅ Clear blocker found (no point continuing)
-- ✅ Obvious answer emerged
-- ❌ Timebox expired (stop and document)
-
-### Red Flags
-- 🚩 Spike extending beyond 1 week
-- 🚩 Writing production-quality code
-- 🚩 Scope creeping beyond research question
-- 🚩 Not documenting findings
-- 🚩 Trying to prove pre-decided solution
-
-### Success Criteria
-Spike is successful when:
-1. Research question answered (even if answer is "no")
-2. Clear recommendation made
-3. Risks identified
-4. Architecture impact understood
-5. Findings documented
-6. Completed within timebox
-
-### Prototype Cleanup
-After spike:
-```bash
-# Archive prototype
-git branch -D spike/[name]  # Delete branch
-# OR move to /experiments directory
-mkdir -p experiments/spike-[name]
-mv [prototype] experiments/spike-[name]/
-
-# Update README
-echo "## Spike: [name]" >> experiments/README.md
-echo "Result: [recommendation]" >> experiments/README.md
-echo "Date: [date]" >> experiments/README.md
-```
+### Gate
+- [ ] Comparison matrix filled with real numbers
+- [ ] Recommendation explicit (don't say "both are fine")
+- [ ] ADR written
+- [ ] Spike branch tagged + NOT merged
 
 ---
 
-## Templates
+## Final Report
 
-### Quick Spike Template (2-4 hours)
 ```markdown
-# Spike: [Name]
-
-## Question
-[Clear question]
+## Spike Complete: {name}
 
-## Research (2 hours)
-- [ ] Option 1 research
-- [ ] Option 2 research
-- [ ] Documentation review
+### Question
+{From DEFINE}
 
-## Decision (30 min)
-- Recommendation: [choice]
-- Reasoning: [why]
+### Recommendation
+**Pick Option {X}** because {top reason backed by spike evidence}
 
-## Next Steps
-- [ ] Next action
-```
+### Evidence
+{Benchmark numbers, screenshots, error logs — link to spike branch}
 
-### Full Spike Template (3-5 days)
-```markdown
-# Spike: [Name]
+### Next step
+- If accepted: `/feature:new` to build it properly
+- If rejected: document why + close the question
 
-## Define (Day 1)
-- Question: [clear question]
-- Success criteria: [list]
-- Timebox: [X days]
+### Time spent
+{Actual vs timebox — note overruns for retrospective}
+```
 
-## Research (Day 1-2)
-- Options explored: [list]
-- Architecture impact: [assessment]
+---
 
-## Prototype (Day 2-3)
-- What: [what we're building]
-- Result: [what we learned]
+## Hard Rules
 
-## Evaluate (Day 4-5)
-- Recommendation: [choice]
-- ADR: [link]
-- Next steps: [list]
-```
+- **Define before building** — undefined spike = unbounded spike
+- **Timebox is sacred** — overrun means the question is wrong, not the answer
+- **Throwaway code** — spike branch never merges to main
+- **Numbers, not vibes** — recommendation must cite measurements
+- **One question per spike** — multiple questions = multiple spikes
 
 ---
 
@@ -518,8 +210,8 @@ echo "Date: [date]" >> experiments/README.md
 
 | When | Use |
 |------|-----|
-| Just need to compare options via docs (no code) | `/research:web` |
-| Spike done, ready to implement | `/feature:new` |
+| Compare options via docs only (no code) | `/research:web` |
+| Spike done, ready to implement properly | `/feature:new` |
 | Spike revealed a bug to investigate | `/fix:root-cause` |
 | Document the ADR as a doc page | `/docs:write` |
 
@@ -527,7 +219,7 @@ echo "Date: [date]" >> experiments/README.md
 
 | Phase | Agent | Purpose |
 |-------|-------|---------|
-| DEFINE | `@clean-architect` | Frame research questions |
+| DEFINE | `@clean-architect` | Frame the question |
 | RESEARCH | `@api-designer` | API / integration research |
 | RESEARCH | `@db-designer` | Data model research |
 | RESEARCH | `@security-audit` | Security implications |