vbounce-engine 2.5.1

package/templates/epic.md

@@ -0,0 +1,203 @@
+<instructions>
+FOLLOW THIS EXACT STRUCTURE. Output sections in order.
+
+1. **YAML Frontmatter**: Epic ID, Status, Ambiguity, Context Source, Release, Owner, Priority, Tags, Target Date
+2. **§1 Problem & Value**: Why (problem), What (solution), Success Metrics
+3. **§2 Scope Boundaries**: IN-SCOPE checkboxes, OUT-OF-SCOPE list
+4. **§3 Context**: Personas, User Journey diagram, Constraints table
+5. **§4 Technical Context**: Affected files, Dependencies, Integrations, Data changes
+6. **§5 Decomposition Guidance**: Story categories checklist + suggested sequence
+7. **§6 Risks & Edge Cases**: Risk table with mitigations
+8. **§7 Acceptance Criteria**: Gherkin scenarios (happy path + error case)
+9. **§8 Open Questions**: Blocking decisions table
+10. **§9 Artifact Links**: Stories list + references
+
+Ambiguity Score:
+- 🔴 High: Scope unclear → Needs refinement
+- 🟡 Medium: Scope clear, tech TBD → Ready for decomposition
+- 🟢 Low: All filled → Ready for Stories
+
+Output location: `product_plans/backlog/EPIC-{NNN}_{epic_name}/EPIC-{NNN}_{epic_name}.md`
+
+Document Hierarchy Position: LEVEL 3 (Charter → Roadmap → **Epic** → Story)
+
+**Codebase research is mandatory when filling §4 Technical Context.** Do NOT guess at affected files, dependencies, or integration points. Read the actual codebase — explore directories, read files listed in upstream documents, understand current architecture — then fill §4 with real file paths and verified dependencies.
+
+Upstream sources:
+- §1 Problem & Value traces to Charter §1.1 (What It Is) and §5 (Key Workflows)
+- §3.3 Constraints inherits from Charter §6 and Roadmap §5 Strategic Constraints
+- §4 Technical Context references Roadmap §3 ADRs for architecture decisions AND actual codebase exploration
+- Metadata.Priority aligns with Roadmap §2 Release Plan epic priorities
+
+Downstream consumers:
+- Stories are decomposed from §5 Decomposition Guidance
+- Story §1 The Spec inherits from Epic §2 Scope Boundaries
+- Story §3 Implementation Guide references Epic §4 Technical Context
+- Delivery Plan §3 Active Sprint pulls stories linked in §9 Artifact Links
+- Risk Registry §1 Active Risks may reference Epic §6 Risks
+
+Do NOT output these instructions.
+</instructions>
+
+---
+epic_id: "EPIC-{ID}"
+status: "Draft / Ready / In Progress / Done"
+ambiguity: "🔴 High / 🟡 Medium / 🟢 Low"
+context_source: "Charter §{section} / Roadmap §{section} / User Input"
+release: "{Release name from Roadmap §2}"
+owner: "{PM/PO name}"
+priority: "P0 - Critical / P1 - High / P2 - Medium"
+tags: ["frontend", "api", "auth"]
+target_date: "{YYYY-MM-DD}"
+---
+
+# EPIC-{ID}: {Epic Name}
+
+## 1. Problem & Value
+> Target Audience: Stakeholders, Business Sponsors
+
+### 1.1 The Problem
+> 1-2 sentences. Why are we doing this?
+
+### 1.2 The Solution
+> High-level what we're building.
+
+### 1.3 Success Metrics (North Star)
+- {Measurable outcome 1}
+- {Measurable outcome 2}
+
+---
+
+## 2. Scope Boundaries
+> Target Audience: AI Agents (Critical for preventing hallucinations)
+
+### ✅ IN-SCOPE (Build This)
+- [ ] {Capability 1}
+- [ ] {Capability 2}
+- [ ] {Capability 3}
+
+### ❌ OUT-OF-SCOPE (Do NOT Build This)
+- {Explicitly excluded capability}
+- {Deferred to EPIC-XXX}
+
+---
+
+## 3. Context
+
+### 3.1 User Personas
+- **{Persona A}**: {Role} - {Primary Goal}
+- **{Persona B}**: {Role} - {Primary Goal}
+
+### 3.2 User Journey (Happy Path)
+```mermaid
+flowchart LR
+    A[User Action] --> B[System Response] --> C[Success State]
+```
+
+### 3.3 Constraints
+| Type | Constraint |
+|------|------------|
+| **Performance** | {e.g., Must complete in < 200ms} |
+| **Security** | {e.g., GDPR compliant, no PII logging} |
+| **Tech Stack** | {e.g., Must use existing UserAPI v2} |
+
+---
+
+## 4. Technical Context
+> Target Audience: AI Agents - READ THIS before decomposing.
+
+### 4.1 Affected Areas
+| Area | Files/Modules | Change Type |
+|------|---------------|-------------|
+| API | `src/api/{file}.ts` | New / Modify |
+| Database | `prisma/schema.prisma` | Add table / Modify |
+| UI | `src/components/` | New component |
+| Config | `.env`, `config/` | Add vars |
+
+### 4.2 Dependencies
+| Type | Dependency | Status |
+|------|------------|--------|
+| **Requires** | EPIC-{ID}: {name} | Done / In Progress / Blocked |
+| **Unlocks** | EPIC-{ID}: {name} | Waiting |
+
+### 4.3 Integration Points
+| System | Purpose | Docs |
+|--------|---------|------|
+| {External API} | {what we use it for} | {link} |
+
+### 4.4 Data Changes
+| Entity | Change | Fields |
+|--------|--------|--------|
+| {Entity} | NEW | id, name, ... |
+| {Entity} | MODIFY | + new_field |
+
+---
+
+## 5. Decomposition Guidance
+> The AI agent will analyze this epic and research the codebase to create small, focused stories. Each story must deliver a tangible, verifiable result — not just a layer of work.
+
+### Affected Areas (for codebase research)
+- [ ] {Area 1: e.g., "Authentication flow in `src/auth/`"}
+- [ ] {Area 2: e.g., "User profile API in `src/api/users.ts`"}
+- [ ] {Area 3: e.g., "Dashboard component in `src/components/Dashboard/`"}
+
+### Key Constraints for Story Sizing
+- Each story should touch 1-3 files and have one clear goal
+- Prefer vertical slices (thin end-to-end) over horizontal layers
+- Stories must be independently verifiable
+
+### Suggested Sequencing Hints
+1. {What must exist first for other work to build on}
+2. {What depends on #1}
+3. {What can run in parallel}
+
+---
+
+## 6. Risks & Edge Cases
+| Risk | Likelihood | Mitigation |
+|------|------------|------------|
+| {e.g., Email delivery delay} | Medium | {e.g., "Resend" button after 30s} |
+| {e.g., Rate limiting hit} | Low | {e.g., Exponential backoff} |
+
+---
+
+## 7. Acceptance Criteria (Epic-Level)
+> How do we know the EPIC is complete? Full user flow.
+
+```gherkin
+Feature: {Epic Name}
+
+  Scenario: Complete Happy Path
+    Given {precondition - user state}
+    When {user completes full flow}
+    Then {end-to-end outcome achieved}
+    And {data persisted correctly}
+
+  Scenario: Key Error Case
+    Given {precondition}
+    When {error condition}
+    Then {graceful handling}
+```
+
+---
+
+## 8. Open Questions
+| Question | Options | Impact | Owner | Status |
+|----------|---------|--------|-------|--------|
+| {decision needed} | A: {x}, B: {y} | Blocks {stories X,Y} | {name} | Open / Decided |
+
+---
+
+## 9. Artifact Links
+> Auto-populated as Epic is decomposed.
+
+**Stories (Status Tracking):**
+> Keep track of where stories live contextually.
+- [ ] STORY-{ID}-01-{story_name} -> Backlog
+- [ ] STORY-{ID}-02-{story_name} -> Active (Sprint XX)
+- [x] STORY-{ID}-03-{story_name} -> Archived (Sprint YY)
+
+**References:**
+- Charter: [PROJECT CHARTER](link)
+- Design: {link}
+- API Spec: {link}

package/templates/hotfix.md

@@ -0,0 +1,58 @@
+<instructions>
+FOLLOW THIS EXACT STRUCTURE. This is a lightweight alternative to the Epic/Story hierarchy for L1 (Trivial) tasks.
+
+1. **YAML Frontmatter**: Hotfix ID, Status, Target Release, Actor, Complexity Label
+2. **§1 The Fix**: What is broken/changing and why
+3. **§2 Implementation Instructions**: Which file(s) to change and what to do
+4. **§3 Verification**: Simple manual test
+
+Output location: `product_plans/{delivery}/HOTFIX-{Date}-{Name}.md`
+
+Document Hierarchy Position: BYPASS
+This document bypasses the Roadmap → Epic → Story hierarchy. It is for L1 (Trivial) changes only (e.g., typos, CSS tweaks, single-line logic fixes).
+
+Constraints:
+- Must touch 1-2 files maximum.
+- Must NOT introduce new architectural patterns.
+- Must NOT require complex new testing infrastructure.
+- If it violates these constraints, the Team Lead MUST escalate it to an Epic.
+
+Do NOT output these instructions.
+</instructions>
+
+---
+hotfix_id: "HOTFIX-{Date}-{Name}"
+status: "Draft / Bouncing / Done"
+target_release: "D-{NN}_{release_name}"
+actor: "{Persona Name / User}"
+complexity_label: "L1 (Trivial)"
+---
+
+# HOTFIX: {Name}
+
+## 1. The Fix
+> What needs to be changed and why.
+
+- **Current Behavior**: {What is wrong}
+- **Desired Behavior**: {What it should be}
+
+---
+
+## 2. Implementation Instructions
+> Direct commands for the Developer Agent.
+
+- **Files to Modify**: `{filepath}`
+- **Instructions**: {e.g., "Change the padding-left from 10px to 20px" or "Fix the typo in the error message."}
+
+> **CONSTRAINT**: If this fix requires modifying more than 2 files, STOP immediately and escalate to the Team Lead. The task must be promoted to an Epic/Story.
+
+---
+
+## 3. Verification
+> How the Human or QA agent will quickly verify this.
+
+- [ ] {Simple step, e.g., "Open the settings modal and verify the button is aligned."}
+- [ ] Automated tests still pass (`npm test`).
+- [ ] **Framework Integrity**: If `.claude/agents/` or `.vbounce/skills/` were modified, log to `.vbounce/CHANGELOG.md`.
+- [ ] **Post-Fix Action**: Run `./.vbounce/scripts/hotfix_manager.sh ledger "HOTFIX: {Name}" "{Brief Fix Description}"`
+- [ ] **Token Tracking**: Run `node .vbounce/scripts/count_tokens.mjs --self --append <this-file> --name Developer`

package/templates/risk_registry.md

@@ -0,0 +1,87 @@
+<instructions>
+FOLLOW THIS EXACT STRUCTURE. Output sections in order 1-4.
+
+1. **YAML Frontmatter**: Set status, last updated, and roadmap ref
+2. **§1 Active Risks**: Table of open risks with phase, source, likelihood, impact, mitigation
+3. **§2 Risk Analysis Log**: Phase-stamped entries appended on state transitions
+4. **§3 Closed Risks**: Resolved/mitigated risks moved here
+5. **§4 Change Log**: Auto-appended on updates
+
+Risk Levels:
+- Likelihood: Low / Medium / High
+- Impact: Low / Medium / High / Critical
+
+Risk Statuses: Open → Mitigating → Mitigated → Closed / Accepted
+
+Output location: `product_plans/strategy/RISK_REGISTRY.md`
+
+Document Hierarchy Position: LEVEL 6 — CROSS-CUTTING
+Charter (why) → Roadmap (strategic what/when) → Epic (detailed what) → Story (how) → Delivery Plan (execution) → **Risk Registry** (risks)
+
+This document is fed by ALL levels of the hierarchy:
+- Charter §6 Constraints → initial strategic risks
+- Roadmap §4 Dependencies → integration and external service risks
+- Roadmap §5 Strategic Constraints → capacity, budget, deadline risks
+- Epic §6 Risks & Edge Cases → feature-level risks
+- Delivery Plan sprint transitions → trigger Risk Analysis Log entries (§2)
+- Architect Agent's Deep Audit findings → may surface new risks
+
+The Risk Registry is reviewed by the Team Lead at sprint boundaries and by the Architect Agent during Deep Audit reviews.
+
+Do NOT output these instructions.
+</instructions>
+
+---
+last_updated: "{YYYY-MM-DD}"
+status: "Active / Archived"
+roadmap_ref: "product_plans/{project}_roadmap.md"
+---
+
+# Risk Registry: {Project Name}
+
+## 1. Active Risks
+
+| ID | Risk | Phase | Source | Likelihood | Impact | Mitigation | Owner | Status |
+|----|------|-------|--------|------------|--------|------------|-------|--------|
+| R-001 | {Risk description} | {Verification/Bounce/Review} | {EPIC-XXX or STORY-XXX-YY-{story_name}} | Low/Medium/High | Low/Medium/High/Critical | {Mitigation strategy} | {Owner} | Open |
+
+**Summary**: {X} Active | {Y} Mitigating | {Z} Accepted
+
+---
+
+## 2. Risk Analysis Log
+
+> Phase-stamped entries. Each entry is appended when a document transitions between V-Bounce phases.
+
+### {YYYY-MM-DD} — Phase: {Verification / Bounce / Review} ({Sprint S-XX})
+**Trigger**: {What caused this analysis — e.g., "Sprint 1 stories moved to Ready to Bounce"}
+**Documents Analyzed**: {List of docs reviewed}
+
+**New Risks Identified**:
+- R-{NNN}: {Risk description} — Source: {doc reference}
+
+**Risks Updated**:
+- R-{NNN}: {Status change and reason}
+
+**Risks Resolved**:
+- R-{NNN}: {Resolution description}
+
+**Recommendation**: {Action items if any}
+
+---
+
+## 3. Closed Risks
+
+| ID | Risk | Resolution | Phase Closed | Closed Date |
+|----|------|------------|--------------|-------------|
+| R-{NNN} | {Risk description} | {How it was resolved} | {Phase} | {YYYY-MM-DD} |
+
+---
+
+## 4. Change Log
+
+<!-- Auto-appended when Risk Registry is updated -->
+
+| Date | Change | By |
+|------|--------|-----|
+| {YYYY-MM-DD} | Initial creation | Architect |

package/templates/roadmap.md

@@ -0,0 +1,174 @@
+<instructions>
+FOLLOW THIS EXACT STRUCTURE. Output sections in order 1-7.
+
+1. **YAML Frontmatter**: Set status, last updated, charter ref, and risk registry ref
+2. **§1 Strategic Context**: Vision (from Charter), primary goal, target users, success metrics
+3. **§2 Release Plan**: Group epics into named releases with exit criteria — NOT sprint-level tracking
+4. **§3 Technical Architecture Decisions**: Key choices with rationale and status (this is the ADR log)
+5. **§4 Dependencies & Integration Map**: External services, cross-epic dependencies, blocking relationships
+6. **§5 Strategic Constraints**: Budget, capacity, hard deadlines, regulatory requirements
+7. **§6 Open Questions**: Unresolved items that affect strategic direction
+8. **§7 Delivery Log**: Release notes for completed deliveries (appended by Team Lead on delivery archive)
+9. **§8 Change Log**: Auto-appended on updates
+
+Output location: `product_plans/strategy/{project}_roadmap.md`
+
+Role of this document:
+- This is the STRATEGIC layer between Charter (why) and Delivery Plan (operational execution).
+- It answers: "What are we shipping, in what order, and what architectural bets are we making?"
+- It does NOT track sprint-level progress — that belongs in the Delivery Plan.
+- It does NOT track individual story status — that belongs in the Delivery Plan.
+- It DOES define release milestones, architectural decisions, and strategic constraints.
+
+Document Hierarchy Position: LEVEL 2 — STRATEGIC
+Charter (why) → **Roadmap** (strategic what/when) → Epic (detailed what) → Story (how) → Delivery Plan (execution) → Risk Registry (risks)
+
+Do NOT output these instructions.
+</instructions>
+
+---
+last_updated: "{YYYY-MM-DD}"
+status: "Planning / Active / MVP Complete / Shipped"
+charter_ref: "product_plans/{project}_charter.md"
+risk_registry_ref: "product_plans/RISK_REGISTRY.md"
+---
+
+# Product Roadmap: {Project Name}
+
+## 1. Strategic Context
+
+| Key | Value |
+|-----|-------|
+| **Vision** | {One sentence from Charter §1.1} |
+| **Primary Goal** | {Main objective for this project window} |
+| **Tech Stack** | {e.g., Next.js, FastAPI, Supabase} |
+| **Target Users** | {Primary user persona from Charter} |
+
+### Success Metrics
+> Pulled from Charter §1.3. These define when the project is "done."
+
+- {Metric 1: e.g., "User signup conversion > 60%"}
+- {Metric 2: e.g., "Page load < 2s on 3G"}
+
+---
+
+## 2. Release Plan
+
+> Group epics into named releases with clear exit criteria. Each release is a shippable milestone.
+> Releases are NOT sprints — a release may span multiple sprints.
+> Sprint-level tracking belongs in the Delivery Plan.
+
+### Release 1: {Release Name} (e.g., "Foundation")
+**Target**: {YYYY-MM-DD or Quarter}
+**Exit Criteria**: {What must be true for this release to ship — e.g., "Users can sign up, log in, and see dashboard"}
+
+| Epic | Priority | Status | Notes |
+|------|----------|--------|-------|
+| EPIC-001: {Name} | P0 | Draft / Ready / In Progress / Done | {Dependencies or blockers} |
+| EPIC-002: {Name} | P1 | Draft | |
+
+### Release 2: {Release Name} (e.g., "Core Features")
+**Target**: {YYYY-MM-DD or Quarter}
+**Exit Criteria**: {e.g., "Full CRUD on all entities, third-party integration live"}
+
+| Epic | Priority | Status | Notes |
+|------|----------|--------|-------|
+| EPIC-003: {Name} | P0 | Draft | |
+
+### Release 3: {Release Name} (e.g., "Polish & Scale")
+**Target**: {YYYY-MM-DD or Quarter}
+**Exit Criteria**: {e.g., "Performance targets met, monitoring in place"}
+
+| Epic | Priority | Status | Notes |
+|------|----------|--------|-------|
+| {Future Epics} | | | |
+
+---
+
+## 3. Technical Architecture Decisions
+
+> Architecture Decision Records (ADRs). Agents reference these when hitting ambiguity.
+> Each decision is immutable once "Decided" — create a new row to override.
+
+| ID | Decision | Choice | Rationale | Status | Date |
+|----|----------|--------|-----------|--------|------|
+| ADR-001 | Auth Provider | {e.g., Supabase Auth} | {Why — cost, speed, integration} | Decided / Proposed / Superseded | {YYYY-MM-DD} |
+| ADR-002 | Database | {e.g., PostgreSQL via Supabase} | {Why} | Decided | |
+| ADR-003 | Hosting | {e.g., Vercel + Railway} | {Why} | Proposed | |
+| ADR-004 | State Management | {e.g., Zustand} | {Why} | Decided | |
+
+---
+
+## 4. Dependencies & Integration Map
+
+> External services, cross-epic dependencies, and anything that blocks progress if unavailable.
+
+### External Dependencies
+| Service | Purpose | Status | Risk if Unavailable |
+|---------|---------|--------|---------------------|
+| {e.g., Stripe API} | Payment processing | Available / Pending Access / TBD | {e.g., "Cannot ship Release 2"} |
+| {e.g., SendGrid} | Transactional email | Available | Low — fallback exists |
+
+### Cross-Epic Dependencies
+| Epic | Depends On | Relationship | Status |
+|------|------------|--------------|--------|
+| EPIC-003 | EPIC-001 | Requires auth system | Blocked / Ready |
+| EPIC-004 | EPIC-002 | Shares data model | In Progress |
+
+---
+
+## 5. Strategic Constraints
+
+> Hard boundaries that shape prioritization and scope. These override feature requests.
+
+| Constraint | Type | Impact | Mitigation |
+|------------|------|--------|------------|
+| {e.g., Launch by Q2 2026} | Deadline | Caps scope to Release 1 + 2 | Cut P2 epics if behind |
+| {e.g., Solo developer} | Capacity | Max 2 epics per sprint | Lean on AI agents for L1-L2 stories |
+| {e.g., GDPR compliance} | Regulatory | Must audit data flows before launch | Include in Release 1 exit criteria |
+| {e.g., $0 infrastructure budget} | Budget | Free-tier only | Supabase free tier + Vercel hobby |
+
+---
+
+## 6. Open Questions
+
+> Unresolved items that affect strategic direction. Operational questions go in the Delivery Plan.
+
+| Question | Options | Impact | Owner | Status |
+|----------|---------|--------|-------|--------|
+| {e.g., "Build mobile app or PWA?"} | A: Native, B: PWA | Affects Release 3 scope | {name} | Open / Decided |
+| {e.g., "Self-host or managed DB?"} | A: Supabase, B: PlanetScale | ADR-002 | {name} | Decided |
+
+---
+
+## 7. Delivery Log
+
+> Appended by Team Lead when a delivery (release) is archived.
+> Each entry is the release notes — a summary of sprint reports from that delivery.
+
+### D-{NN}: {Release Name}
+**Delivered**: {YYYY-MM-DD}
+**Release Tag**: v{VERSION}
+**Delivery Folder**: `product_plans/archive/D-{NN}_{release_name}/`
+
+**Release Notes**:
+> {Summary of what was shipped — compiled from sprint reports. Key features, important fixes, architectural changes.}
+
+**Metrics**:
+| Metric | Value |
+|--------|-------|
+| Stories Delivered | {X} |
+| Stories Escalated | {Y} |
+| Total Sprints | {N} |
+| Average Bounce Ratio | {X}% |
+| Average Correction Tax | {X}% |
+
+---
+
+## 8. Change Log
+
+<!-- Auto-appended when Roadmap is updated -->
+
+| Date | Change | By |
+|------|--------|-----|
+| {YYYY-MM-DD} | Initial creation from Charter | Architect |

package/templates/spike.md

@@ -0,0 +1,143 @@
+<instructions>
+FOLLOW THIS EXACT STRUCTURE. Output sections in order 1-8.
+
+1. **YAML Frontmatter**: Spike ID, Parent Epic, Parent Story (optional), Status, Ambiguity Before, Time Box, Owner, Tags, Created
+2. **§1 Question**: The specific unknown to resolve
+3. **§2 Constraints**: Time box, scope limits, what is NOT being investigated
+4. **§3 Approach**: Investigation method
+5. **§4 Findings**: Evidence, data, observations discovered
+6. **§5 Decision**: Choice made + rationale + alternatives rejected
+7. **§6 Residual Risk**: What's still uncertain after the spike
+8. **§7 Affected Documents**: Checklist of upstream/downstream docs to update on close
+9. **§8 Change Log**: Modification history
+
+Spike Statuses: Open → Investigating → Findings Ready → Validated → Closed
+
+Output location: `product_plans/backlog/EPIC-{NNN}_{name}/SPIKE-{EpicID}-{NNN}-{topic}.md`
+
+Document Hierarchy Position: LEVEL 3.5 (Charter → Roadmap → Epic → **Spike** / Story)
+Spikes are children of Epics, siblings of Stories. They travel with their Epic folder (archiving is automatic).
+
+Upstream sources:
+- §1 Question derives from parent Epic §8 Open Questions (blocking items)
+- §3 Approach references parent Epic §4 Technical Context
+- Roadmap §3 ADRs informs existing architectural decisions
+
+Downstream consumers:
+- §4 Findings → parent Epic §4 Technical Context (update with new knowledge)
+- §5 Decision → Roadmap §3 ADRs (if architectural decision)
+- §6 Residual Risk → Risk Registry §1 Active Risks (if new risk identified)
+- §5 Decision → parent Story §3 Implementation Guide (if story-level spike)
+
+Agent handoff:
+- Team Lead creates the spike from template, links to Epic §9
+- Developer investigates (fills §4 Findings and §5 Decision)
+- Architect validates findings against Safe Zone (Findings Ready → Validated)
+- Team Lead propagates findings to affected documents (Validated → Closed)
+
+Do NOT output these instructions.
+</instructions>
+
+---
+spike_id: "SPIKE-{EpicID}-{NNN}-{topic}"
+parent_epic_ref: "EPIC-{ID}"
+parent_story_ref: "(optional — omit for epic-level spikes)"
+status: "Open / Investigating / Findings Ready / Validated / Closed"
+ambiguity_before: "🔴 High / 🟡 Medium"
+time_box: "e.g., 4 hours / 1 day"
+owner: "Developer / Architect"
+tags: []
+created: "YYYY-MM-DD"
+---
+
+# SPIKE-{EpicID}-{NNN}: {Topic}
+
+## 1. Question
+> The specific unknown to resolve. Derived from Epic §8 Open Questions.
+
+{What exactly do we need to find out? Frame as a single, concrete question.}
+
+---
+
+## 2. Constraints
+> What boundaries apply to this investigation.
+
+| Constraint | Value |
+|------------|-------|
+| **Time Box** | {e.g., 4 hours / 1 day} |
+| **Scope Limit** | {What IS being investigated} |
+| **Out of Scope** | {What is NOT being investigated — prevents scope creep} |
+
+---
+
+## 3. Approach
+> How the investigation will be conducted.
+
+**Method:** {Code exploration / Prototyping / Benchmarks / Doc research / Proof of concept}
+
+### Steps
+1. {First investigation step}
+2. {Second investigation step}
+3. {Third investigation step}
+
+---
+
+## 4. Findings
+> Evidence, data, and observations discovered during investigation.
+> Filled by the Developer during the Investigating phase.
+
+### Evidence
+- {Observation 1 — with data or code references}
+- {Observation 2}
+
+### Data
+| Metric | Value | Notes |
+|--------|-------|-------|
+| {e.g., Response time} | {value} | {context} |
+
+---
+
+## 5. Decision
+> Choice made based on findings. Becomes an ADR if architectural.
+
+### Chosen Approach
+{What we decided to do and why.}
+
+### Alternatives Rejected
+| Alternative | Why Rejected |
+|-------------|--------------|
+| {Option A} | {Reason} |
+| {Option B} | {Reason} |
+
+### ADR Required?
+- [ ] Yes — create ADR in Roadmap §3 (decision affects architecture)
+- [ ] No — decision is implementation-level only
+
+---
+
+## 6. Residual Risk
+> What's still uncertain after the spike. Feeds Risk Registry if non-trivial.
+
+| Risk | Likelihood | Impact | Mitigation |
+|------|------------|--------|------------|
+| {Remaining unknown} | {Low/Medium/High} | {description} | {how to manage} |
+
+---
+
+## 7. Affected Documents
+> Checklist of upstream/downstream docs to update when closing this spike.
+> ALL items must be checked before spike status can move to Closed.
+
+- [ ] Epic §4 Technical Context — update with findings
+- [ ] Epic §8 Open Questions — mark resolved
+- [ ] Epic §9 Artifact Links — add spike reference
+- [ ] Roadmap §3 ADRs — if architectural decision (see §5)
+- [ ] Risk Registry §1 — if new risk identified (see §6)
+- [ ] Story §3 Implementation Guide — if story-level spike
+
+---
+
+## 8. Change Log
+| Date | Author | Change |
+|------|--------|--------|
+| {YYYY-MM-DD} | {name} | Created spike |