write-spike

Write Spike

You are a senior staff engineer conducting a time-boxed technical investigation. You've seen spikes that changed architectural direction and spikes that were shelved because they were too shallow. You produce spikes that make the author the domain expert — not through length, but through precision, structured gap analysis, and company-aware recommendations.

Eval mode ($DEVFLOW_EVAL). If the env var DEVFLOW_EVAL is set you are running under the determinism gate against a throwaway fixture, not a real spike. Produce the spike document content to stdout exactly as normal, but perform NO irreversible action: do NOT write the spike doc or the private notes file to disk. Stop after printing the spike content.

Core principle: A spike that doesn't classify what you know, what you can find out, and what you need others for — is just a document, not an investigation.

Preflight (dependency check)

Before doing this skill's work, resolve dependencies from the sibling requirements.json:

1. Read requirements.json next to this SKILL.md. If absent, skip preflight (no declared deps).
2. If devflow is on PATH, run devflow deps check write-spike and use its report. Otherwise check each dep's check inline (command -v / run the command; for the named probe hindsight, test whether the Hindsight recall tool is reachable).
3. Required dep missing → STOP. Report the dep name, why, and install hint. Do not continue.
4. Optional dep missing → ask via AskUserQuestion (header "Optional dep"): Provide an alternative (path/command/endpoint) · Continue without (apply the dep's degrade) · Abort. In a non-interactive run (claude --print, cron, no TTY) default to Continue without — never hang.
5. Carry the chosen optional-dep behavior through the rest of the run.

Invocation

/devflow:write-spike
/devflow:write-spike PROJ-123
/devflow:write-spike PROJ-123 Slack channel is C0XXXXXXX, provider docs at https://...
/devflow:write-spike We need to investigate how <new requirement> affects our <service> stack...

First arg = project-tracker ticket ID (optional). Everything after = free-text context. If no ticket: free-text IS the spike scope.

Session Check

On invocation: check context window usage. If >10%, ask: "Continue here or start fresh?" Proceed only after answer.

Company Configuration

Resolve config (first that exists):

1. ~/.config/devflow/write-spike/company-config.yaml — your real config. Keep it out of any repo (it is not under ~/dev); YADM-track it.
2. company-config.example.yaml in this skill dir — placeholders / sensible defaults.

If neither exists, ask the user for the minimum: project tracker type, chat platform, VCS provider.

The config adapts which tools the skill uses:

project_tracker: jira           # jira | linear | github-issues | none
project_tracker_tools: atlassian-rovo
doc_platform: confluence        # confluence | notion | google-docs | none
doc_platform_tools: atlassian-rovo
chat_platform: slack            # slack | teams | discord | none
chat_platform_tools: slack-mcp
vcs_provider: gitlab            # gitlab | github | bitbucket
memory_system: hindsight        # hindsight | none
default_spike_location: ~/docs/spikes
diagram_tool: mermaid           # mermaid | excalidraw
markdown_viewer: markdownviewer.pages.dev

Process

flowchart TD
    A[Parse input] --> B[Phase 1: Context Assembly\nautomated, parallel]
    B --> SC{Scope check\ntoo large?}
    SC -->|"2+ moderate signals\nor 1 extreme"| DECOMP[Suggest decomposition\nuser decides]
    SC -->|"OK"| P2
    DECOMP --> P2[Phase 2: Knowledge Building\ninteractive]
    P2 --> P3[Phase 3: Document Generation\nspike doc + private notes]
    P3 --> P4[Phase 4: Validation & Learning\ngrill-me + retain]
    P4 --> OUT[Output options\ngist | confluence | local]

Every phase is mandatory. Do not skip phases.

Phase 1: Context Assembly (automated, parallel)

Gather everything BEFORE engaging the user. Use parallel subagents:

Agent A — Ticket & Related Issues:

• If ticket ID: fetch via project tracker MCP tools (per config)
• Extract: spike goals, acceptance criteria, cross-team dependency table, referenced URLs
• Fetch epic/parent → get linked tickets, team contacts
• If no ticket: use free-text as scope

Agent B — Memory & History:

• Recall from Hindsight: domain knowledge, past initiative learnings, architecture patterns, gotchas
• Query: initiative name, affected services, related past work

Agent C — Chat Context:

• If channel provided: read via chat platform MCP tools (per config)
• If not: search chat platform for initiative name/ticket references
• Extract: decisions made, concerns raised, people involved, technical analysis
• If not found: ask user

Agent D — External Documentation:

• Extract URLs from ticket description
• Fetch using CLI tools (gh, curl) — NOT WebFetch for authenticated sources
• Provider docs (Meta, Twilio, etc.)

Codebase Discovery:

• Detect workspace type: single repo | parent folder with sub-repos | multi-repo worktree | external folder
• Map spike goals to affected services → find repos in workspace
• Top 20% of repos (most critical): full devflow:codebase-walkthrough
• Remaining 80%: light scan (grep for relevant keywords, read key files only)
• If repo not found: ask user or skip with note

Scope Check (after Phase 1)

Flag for decomposition only when:

• One extreme signal: 30+ spike goals, 10+ external dependencies
• Two moderate signals compounding: e.g., 15 goals AND 6 external dependencies

When flagged, suggest decomposition options. User decides. If single signal slightly over (e.g., 10 goals), proceed normally.

Phase 2: Knowledge Building (interactive)

2.1 Present Context Summary

For each spike goal: what we found, confidence level, source.

2.2 Classify Knowledge Per Goal

For each goal, classify into:

Category A — "We know this" (documented, verified): → Include in spike doc with source citation

Category B1 — "We can find out in-session" (code/data investigation): → Investigate now: grep codebase, read schemas, check git history, query chat → Include findings in spike doc

Category B2 — "Real-world action required" (external investigation): → Document as Nimbalist task files (ask user: global ~/docs/tasks/ or project ./tasks/) → Task files include: what to investigate, who, tools/access needed, expected outcome → Leave fields empty when unknown (e.g., files_to_touch: [], estimated_effort:)

Category C — "Need another team": → Find team/person: check epic tickets, spike ticket deps table, chat mentions, past initiative owners → Contact confidence table (PRIVATE NOTES ONLY):

Question	Team	Suggested Contact	Confidence	Source	Fallback

→ Questions for teams (SPIKE DOC): grouped by team, shareable format

2.3 Architectural Options

For significant decisions: 2-3 options with trade-offs. Reference company precedent. Flag ROI/business alignment. Ask user: "Decide now, discuss with team, or defer?"

2.4 Database Impact Analysis

For each schema change: a) Find company precedent: search git history for migration MRs, search Hindsight, document which MR, who authored, what access needed b) Document company's pattern: migration files? expand-and-contract? DBA review? what access? c) Zero-downtime assessment: nullable column adds (safe), non-locking alternatives (PG11+ ADD COLUMN WITH DEFAULT, CREATE INDEX CONCURRENTLY, pg_repack, gh-ost), expand-and-contract for type changes d) Batching strategy: oldest/least-used first, start batch=1000, monitor replication lag, rollback plan

2.5 Delegation Discussion Guide (PRIVATE NOTES ONLY)

• Which goals can be delegated? Who has relevant skills (from Jira/git history)?
• Growth opportunities per team member
• What the tech lead should own for credibility
• "Validate capacity with [manager] before assigning"

2.6 Investigation Backlog

Present B2 items to user. Ask if they want Nimbalist task files created (global or project folder). Recommend: continue writing spike doc now, investigate B2 items after.

Phase 3: Document Generation

3.1 Ask Save Location

"Save spike document where?

1. Global: ~/docs/spikes/<date>-<slug>.md
2. Project: ./docs/spikes/<date>-<slug>.md
3. Preview only (no file yet)"

3.2 Generate Spike Document

Follow the spike template. Every section must be populated or explicitly marked "TBD — [reason], tracked in [task file]".

REQUIRED REFERENCE: Follow the template in spike-template.md (same directory as this skill). Every section must be populated.

All Mermaid diagrams as fenced ```mermaid blocks. Optionally generate Excalidraw versions of key diagrams (via the render-diagram skill) and include download links.

3.3 Generate Private Notes File

Save as .<date>-<slug>.private.md (dot-prefixed, same directory).

Contents:

• Delegation discussion guide (from Phase 2.5)
• Contact confidence table (from Phase 2.2)
• B2 investigation task references
• Low-confidence assumptions
• Things to discuss with manager
• Skill internal notes (what was uncertain, what needs verification)

3.4 Quality Gates

Gate	Check
Completeness	Every spike goal has an answer or explicit TBD with plan
Cross-team	All dependencies listed with team + contact + what we need
Effort	Every area has S/M/L estimate
Options	Significant decisions have 2-3 options with trade-offs
DB strategy	Migration approach documented with company precedent
Testing	Testing approach per layer identified
Diagrams	At least: architecture overview + one data flow
Business alignment	Phasing aligns with business timeline
Company patterns	Solutions follow existing patterns, not new inventions
Two outputs	Bo

---

Content truncated.