| name | spike-investigation |
| description | Investigate a technical spike by gathering requirements interactively, analyzing the codebase with grep and read tools, researching libraries and technologies, evaluating options, and producing a structured report with a high-level proposals doc (for managers/PMs/designers) and detailed technical analysis. Uses Monte Carlo simulation for timeline forecasting with confidence levels. Optionally integrates with JIRA if a ticket ID is referenced. |
Spike Investigation - Technical Research & Analysis
Investigate a technical spike by gathering requirements, analyzing the codebase, researching libraries, and creating a comprehensive recommendation report with a stakeholder-facing proposals document.
Spike Topic: $ARGUMENTS (e.g., "React 19 migration feasibility" or "GraphQL implementation options" or "PRO-1234")
Investigation Process:
0. Check for Previous Spike Analysis
REPORT_BASE="${REPORT_BASE:-$HOME/Documents/technical-analysis}"
SPIKE_TOPIC="$ARGUMENTS"
SPIKE_ID=$(echo "$SPIKE_TOPIC" | sed 's/[^a-zA-Z0-9]/-/g' | tr '[:upper:]' '[:lower:]' | \
sed 's/--*/-/g' | sed 's/^-\|-$//g')
SPIKE_DIR="${REPORT_BASE}/spikes/${SPIKE_ID}"
REPORT_FILE="${SPIKE_DIR}/analysis.md"
RESEARCH_FILE="${SPIKE_DIR}/research.md"
RECOMMENDATIONS_FILE="${SPIKE_DIR}/recommendations.md"
PROPOSALS_FILE="${SPIKE_DIR}/proposals.md"
if [[ -f "$REPORT_FILE" ]]; then
echo "🔍 Found previous spike analysis for: $SPIKE_TOPIC"
echo "📁 Location: $SPIKE_DIR"
sed -n '/## Problem Statement/,/## Context/p' "$REPORT_FILE" | head -20
sed -n '/## Proposal/,/## Test Plan/p' "$REPORT_FILE" | head -30
LAST_MODIFIED=$(stat -f "%Sm" -t "%Y-%m-%d %H:%M" "$REPORT_FILE" 2>/dev/null || \
date -r "$REPORT_FILE" "+%Y-%m-%d %H:%M" 2>/dev/null || echo "Unknown")
echo "📅 Last Analysis: $LAST_MODIFIED"
grep -A 10 "### Action Items" "$REPORT_FILE" | grep "^- \[ \]" | head -5 || true
echo ""
echo "Continue from previous findings (A) or start fresh (B)?"
else
echo "🆕 No previous analysis found for: $SPIKE_TOPIC"
echo "📁 Will create at: $SPIKE_DIR"
fi
1. Gather Spike Requirements & Context
mkdir -p "$SPIKE_DIR"
if echo "$SPIKE_TOPIC" | grep -qE "[A-Z]{2,}-[0-9]+"; then
JIRA_KEY=$(echo "$SPIKE_TOPIC" | grep -oE "[A-Z]{2,}-[0-9]+" | head -1)
echo "🎫 Found JIRA reference: $JIRA_KEY"
if command -v jira >/dev/null 2>&1; then
jira issue view "$JIRA_KEY" 2>/dev/null && JIRA_CONTEXT_FOUND=true || JIRA_CONTEXT_FOUND=false
else
echo "⚠️ jira CLI not available — continuing without ticket context"
fi
fi
Then prompt the user for:
📋 Business Context:
- What business problem are we trying to solve?
- What are the success criteria for this spike?
- What's the expected timeline/deadline?
- What's the impact if we don't implement this?
🔧 Technical Scope:
- Which parts of the system are in scope?
- Are there specific technologies to evaluate?
- What are the current pain points being addressed?
- Are there any constraints or limitations?
🔬 Research Areas:
- What specific questions need answering?
- What alternatives should be compared?
- Are there libraries/frameworks to investigate?
- Is a proof-of-concept needed?
2. Codebase Analysis
Use grep, find, and read tools to understand the current system:
echo "📁 Analyzing current project structure..."
find . -name "package.json" -not -path "*/node_modules/*" | head -5
cat package.json 2>/dev/null | jq '{name, version, dependencies, devDependencies}' 2>/dev/null || \
grep -A 5 '"dependencies"' package.json | head -20
echo "🔍 Scanning for relevant patterns..."
grep -rn "import.*from" src/ --include="*.ts" 2>/dev/null | \
sed "s/.*from '//;s/'.*//" | sort | uniq -c | sort -rn | head -20
find src/ -name "*.ts" -o -name "*.tsx" -o -name "*.py" 2>/dev/null | \
xargs grep -l "spike-relevant-keyword" 2>/dev/null | head -20
grep -rn "relevant-pattern" src/ 2>/dev/null | head -10
git log --oneline --since="3 months ago" --all | head -20
Document findings:
- Current technology stack and versions
- Architecture patterns in use
- Files and components that would be impacted
- Existing dependencies relevant to the spike
- Technical debt or pain points in the affected area
- Test coverage in the area of impact
3. Technology Research
For each library or technology being evaluated:
grep '"library-name"' package.json package-lock.json 2>/dev/null
cat node_modules/library-name/CHANGELOG.md 2>/dev/null | head -100
grep -rn "import.*library-name" src/ --include="*.ts" 2>/dev/null | head -20
grep -rn "from 'library-name'" src/ --include="*.ts" 2>/dev/null | head -20
Research each option using available knowledge and official documentation. For each technology, assess:
- Maturity & stability — production-ready? breaking changes?
- Community & support — actively maintained? known issues?
- Performance characteristics — benchmarks, known bottlenecks
- Migration path — complexity of moving from current state
- Developer experience — setup complexity, tooling, debugging
- Security — known vulnerabilities, audit status
- Bundle size / footprint — if relevant to the spike
4. Comparison Framework
Build a weighted scoring matrix based on what matters for this specific spike:
### Technology Comparison Matrix
| Criteria | Option A | Option B | Option C | Weight |
| ---------------------------- | -------- | -------- | -------- | ------ |
| Performance | /10 | /10 | /10 | % |
| Developer Experience | /10 | /10 | /10 | % |
| Migration Cost | /10 | /10 | /10 | % |
| Community/Support | /10 | /10 | /10 | % |
| Long-term Viability | /10 | /10 | /10 | % |
| [Criteria specific to spike] | /10 | /10 | /10 | % |
| **Weighted Score** | | | | 100% |
Weights should reflect the actual business priorities stated in Step 1.
5. Proof of Concept (if applicable)
If the spike requires validation through code:
mkdir -p "$SPIKE_DIR/poc"
Record:
- Scope of what was built
- Time taken vs estimate
- Performance measurements (before/after)
- Developer experience notes
- Unexpected blockers or discoveries
6. Review Estimation Playbook
Before generating timeline estimates, read the Estimation & Forecasting Playbook for the team's estimation conventions:
SKILL_DIR="$(dirname "$0")"
cat "${SKILL_DIR}/estimation-playbook.md"
Key principles to apply:
- Frame delivery as confidence intervals, not single dates or vague ranges
- Use P85 as the recommended planning target ("We're 85% confident we can deliver by [date]")
- Stories should fit within 2–3 days of work — if a phase has stories larger than that, split them
- If historical throughput data (velocity per sprint) is available, use it to calibrate estimates
- The Monte Carlo simulation is the primary forecasting tool — compute PERT-based confidence intervals for every proposal
7. Generate Reports
mkdir -p "$SPIKE_DIR"
if [[ -f "$REPORT_FILE" ]]; then
BACKUP_DIR="${SPIKE_DIR}/backups/$(date +%Y%m%d_%H%M%S)"
mkdir -p "$BACKUP_DIR"
cp "$REPORT_FILE" "$BACKUP_DIR/" 2>/dev/null || true
cp "$RESEARCH_FILE" "$BACKUP_DIR/" 2>/dev/null || true
cp "$RECOMMENDATIONS_FILE" "$BACKUP_DIR/" 2>/dev/null || true
cp "$PROPOSALS_FILE" "$BACKUP_DIR/" 2>/dev/null || true
fi
Generate the following deliverables. The proposals doc is the primary stakeholder-facing output. The analysis, research, and recommendations files provide the deep technical backing.
7a. proposals.md — High-Level Proposal (for managers, PMs, designers)
This is the document stakeholders read. It should be written in plain language, explain the "why" before the "what," and present options with clear tradeoffs.
The template below defines required content sections, not literal headings. Use friendly, plain-language titles that fit the topic. Examples are shown in [brackets].
# [Proposal Title — plain language, not jargon]
**Date:** [Date]
**Status:** Ready for Decision
**Audience:** Product, Design, Engineering Leadership
---
## Table of Contents
[Number all sections. Use your friendly titles here.]
---
## [Problem Statement — e.g., "Why We're Here"]
[2–4 sentences max. What is the problem? Why does it matter to the business? What happens if we don't act?
Write for someone who doesn't know the codebase. No jargon.]
---
## [Context — e.g., "What We Found"]
[Background that stakeholders need to understand the proposal:
- Current state (what exists today)
- How we got here (decisions, history, accumulated debt)
- Key numbers that quantify the problem (counts, percentages, impact metrics)
- What's already working well (acknowledge strengths)
- Bugs or issues discovered during investigation
Use tables for structured data. Explain technical concepts in plain language — use analogies, not acronyms. If something needs a technical deep-dive, put it in an appendix and link to it.]
---
## [Proposal — e.g., keep "Proposal" or use the topic name]
[One short paragraph framing the options and the recommendation.]
### [Option 1 — e.g., "Harden First, Then Theme"]
**The Idea**
[1 paragraph explaining the approach in non-technical terms.]
**Phases at a Glance**
| Phase | Name | What Happens | Duration | Who |
| ----- | ---- | ------------ | -------- | --- |
| ... | ... | ... | ... | ... |
[Phase names should be human-readable — "Visual Inventory," not "Phase 0."]
**Pros**
- [Frame in terms of business/team value, not technical elegance]
**Cons**
- [Be honest about costs and tradeoffs]
**Timeline**
| Confidence | Weeks | Interpretation |
| ---------- | ----- | ----------------------------------- |
| P50 | ~X | Even odds we finish by this date |
| P75 | ~X | Reasonably confident |
| P85 | ~X | High confidence — plan to this |
| P95 | ~X | Near certain (buffer for surprises) |
[No methodology details here — the Estimation Methodology appendix explains how these were calculated.]
---
### [Option 2 — plain language name]
[Same structure as Option 1]
---
### Side-by-Side Comparison
| Dimension | Option 1 | Option 2 |
| -------------------------------- | ------------- | ------------- |
| **Time to delivery (P50 / P85)** | ~X / ~Y weeks | ~X / ~Y weeks |
| [Key differentiator 1] | ... | ... |
| [Key differentiator 2] | ... | ... |
| **Cost of doing this again** | ... | ... |
---
### Our Recommendation
**[Option N]**, because:
1. [Reason 1 — strongest argument]
2. [Reason 2]
3. [Reason 3]
---
### Decisions Needed
1. **Which option?**
2. **If Option 1:** [Key questions that must be answered]
3. **If Option 2:** [Key questions that must be answered]
4. **Either way:** [Shared questions]
---
## [Risk — e.g., "What Could Go Wrong"]
### Risks Shared by All Options
| Risk | Probability | Impact | Mitigation |
| ---- | ------------ | ------------ | ---------- |
| ... | Low/Med/High | Low/Med/High | ... |
### Risks Unique to [Option 1]
| Risk | Probability | Impact | Mitigation |
| ---- | ----------- | ------ | ---------- |
### Risks Unique to [Option 2]
| Risk | Probability | Impact | Mitigation |
| ---- | ----------- | ------ | ---------- |
---
## [Test Plan — e.g., "How We'll Verify This Works"]
[Per-option verification strategy:
- Automated testing (unit, integration, e2e, visual regression)
- Manual verification approach
- Rollback plan if things go wrong
- Definition of done]
---
## Resources
- [JIRA ticket link if applicable]
- [Design documents or Figma links]
- [Related spikes or prior art]
- [Library/framework documentation]
- [Internal runbooks or playbooks]
---
## Appendix: [Topic-specific detail]
[Appendices hold everything that supports the main narrative but would overwhelm it:
- Current state detail (architecture, file inventory, dependency maps)
- Per-option phase detail (gate criteria, task breakdowns, dependencies)
- Design team commitments and dependencies
- Measuring progress (metrics table with starting values and targets)
The body should stand on its own — appendices are for stakeholders who want to go deeper.]
---
## Appendix: Estimation Methodology
> For the full estimation framework, see the **Estimation & Forecasting Playbook**.
### Monte Carlo Simulation
Timeline estimates in this document use **Monte Carlo simulation** — a probabilistic forecasting method that replaces traditional deadline-based estimates with confidence intervals. Instead of saying "We'll finish in 12 weeks," we say "We're 85% confident we'll finish within 15 weeks."
This approach aligns with how we plan sprints: we use historical velocity averages and commit to ~90–95% of capacity. Monte Carlo extends this thinking beyond the sprint to larger initiatives.
### How It Works
1. **Input estimates per phase** — each phase gets three estimates:
| Estimate | Meaning |
| ------------------- | -------------------------------------------------------------------------- |
| **Optimistic (O)** | Everything goes well — no blockers, no surprises |
| **Most Likely (M)** | Realistic expectation based on the known scope |
| **Pessimistic (P)** | Things go wrong — integration issues, review cycles, unexpected edge cases |
2. **Run 10,000 simulations** — each simulation randomly samples from a PERT distribution (weighted toward Most Likely) for every phase, then sums the durations.
3. **Get probabilistic outcomes** — the 10,000 runs produce a probability distribution for the total project duration.
### Reading the Confidence Intervals
| Level | Meaning | Use For |
| ------- | ------------------------------------ | ----------------------------------------------------------------------------------- |
| **P50** | 50% chance of finishing by this date | Optimistic planning |
| **P75** | 75% chance | Reasonable expectation |
| **P85** | 85% chance | **Recommended planning target** — "We're 85% confident we can deliver by this date" |
| **P95** | 95% chance | Conservative — accounts for multiple things going wrong |
When communicating with stakeholders, frame delivery as confidence intervals: "We're 85% confident we can deliver this by [date]." This is more honest and useful than a single date or a vague range.
### Input Estimates
[Table of O/M/P estimates per phase for each option. Example:]
**Option 1:**
| Phase | Optimistic | Most Likely | Pessimistic |
| ---------------- | ---------- | ----------- | ----------- |
| Phase 1 — [Name] | X wks | Y wks | Z wks |
| Phase 2 — [Name] | X wks | Y wks | Z wks |
**Option 2:**
| Phase | Optimistic | Most Likely | Pessimistic |
| ---------------- | ---------- | ----------- | ----------- |
| Phase 1 — [Name] | X wks | Y wks | Z wks |
| Phase 2 — [Name] | X wks | Y wks | Z wks |
### Calibration
These estimates should be recalibrated as work begins. Per the Estimation & Forecasting Playbook:
- **After the first phase completes:** compare actual vs estimate at retrospective. Were estimates inflated, deflated, or disrupted by unplanned work? Adjust subsequent phases.
- **With historical velocity data:** if the team tracks throughput (stories or points completed per sprint), use that data directly — randomly sample from past sprint velocities instead of using phase-level PERT estimates. This gets more accurate over time.
- **Each sprint:** update remaining phase estimates based on what's been learned. Re-run simulation. Over time, velocity and cycle time stabilize, making simulations more accurate and planning less stressful.
### How We Computed These Numbers
The PERT formula weights the Most Likely estimate: **Mean = (O + 4M + P) / 6**. Standard deviation: **σ = (P − O) / 6**. Each phase is sampled from this distribution 10,000 times, and sequential phases are summed per simulation to produce the total project distribution. The confidence levels above are percentiles of that distribution.
Writing guidelines for the proposals doc:
- Friendly section titles. The template sections (Problem Statement, Context, Proposal, etc.) define the required content, not the literal headings. Use plain-language titles that read naturally — e.g., "Why We're Here" instead of "Problem Statement," "What We Found" instead of "Context," "Ship the New Theme" instead of "Phase 4." The document should feel like a narrative, not a form.
- No jargon in the document body. The body is for managers, PMs, and designers. Technical terms (PERT, SCSS,
::ng-deep, M2/M3) must be explained in plain language when first used, or kept out of the body entirely. If a concept needs technical detail to be understood, put it in an appendix and link to it. Method details like "10,000 iterations" or "PERT distributions" belong in the Estimation Methodology appendix, not inline with the timeline tables.
- Details in the appendices. The main body tells the story: what's the problem, what are the options, what do we recommend, what decisions are needed. Appendices hold the evidence: codebase audits, per-phase task breakdowns, gate criteria, estimation inputs, methodology explanations. Stakeholders who want to go deeper can — but the core narrative stands on its own without them.
- Lead with "why" before "what." Problem and context come before any solution.
- Be honest about tradeoffs. Every option has real cons. Don't soft-pedal them.
- Quantify everything possible. Numbers (counts, percentages, weeks) are more persuasive than adjectives.
- Use the comparison table. Stakeholders skim — the side-by-side table is often the first thing they read.
- Timelines use confidence levels, not ranges. Instead of "8–12 weeks," say "P50: ~10 weeks, P85: ~11 weeks." Link to the estimation appendix for methodology.
7b. analysis.md — Detailed Technical Analysis
The deep-dive companion to the proposals doc. Contains the full codebase audit, quantified findings, and technical detail that backs up the proposals.
# Spike: [SPIKE_TOPIC]
**Date:** [Investigation Date]
**Status:** [Complete / In Progress]
**Author:** [Name]
---
## Problem Statement
[Same as proposals.md — keep in sync]
---
## Context
[Detailed technical context — codebase structure, dependency analysis, file counts, architecture diagrams, code examples. This section is longer and more technical than the proposals.md version.]
---
## Findings
[Quantified codebase analysis results. Tables of counts, file inventories, pattern catalogs. Everything that supports the numbers in the proposals doc.]
---
## Options Analysis
[Technical deep-dive into each option — architecture changes, migration paths, code examples (before/after), dependency implications, performance analysis.]
---
## Recommendation
[Technical recommendation with detailed justification. May include implementation sequencing, architecture decision records, and technical prerequisites.]
7c. research.md — Raw Research Notes
Detailed notes for each technology investigated — code examples, version history, community signals, integration discoveries, API comparisons.
7d. recommendations.md — Implementation Guidance
Standalone implementation guidance: architecture changes, development workflow updates, code examples before/after, process improvements, monitoring/alerting setup.
Output Summary
The spike investigation produces these deliverables in $SPIKE_DIR:
| File | Audience | Purpose |
|---|
proposals.md | Managers, PMs, designers | High-level proposal with options, tradeoffs, Monte Carlo timelines, and decisions needed |
analysis.md | Engineering | Deep technical analysis backing the proposals |
research.md | Engineering | Raw research notes per technology |
recommendations.md | Engineering | Implementation guidance and architecture decisions |
Notes:
REPORT_BASE defaults to $HOME/Documents/technical-analysis; override with env var- JIRA CLI (
jira) is optional — only needed if a ticket ID is referenced in the spike topic
- The comparison matrix weights should reflect actual business priorities, not defaults
- POC is encouraged but optional — use judgment based on uncertainty and risk
- Supports continuation from previous analyses with automatic backup
- The proposals doc is the primary deliverable — it's what gets shared with stakeholders
- Monte Carlo estimates replace flat ranges (e.g., "8–12 weeks") with confidence intervals (P50/P75/P85/P95)
- Compute PERT-based confidence intervals inline — no separate simulation scripts needed
