Rig spike

Research Spike

A spike is a time-boxed investigation whose deliverable is knowledge, not shipped code. You answer a specific question, surface the trade-offs, and recommend a path — so the team can plan implementation with confidence instead of guessing.

Use a spike when the work is uncertain: feasibility is unknown, there are multiple viable approaches, an unfamiliar API/library is in play, or scope can't be estimated until something is prototyped. If the path is already clear and it's just work to be done, skip the spike and go straight to implementation planning.

Configuration

Reads .rig/config.json:

• sourceScope[0] — the default code scope explorers map first (default: src).
• tracker.provider — linear | github | none (default: none). When none, skip all tracking-ticket steps and deliver the writeup in chat only. When set, optionally create a Spike: tracking ticket and post findings back to it.
• tracker.team / tracker.project — where a Linear tracking ticket is filed, when the provider is linear.
• agents.architect — the project's name for the canonical architect role (default: architect). Explore and Plan are Claude Code built-ins and are used as-is.

If the file is absent, use the defaults above (treat the tracker as none) and note you're running unconfigured.

Core rules of a spike

• Time-box it. Decide the budget up front (default: half a day / ~4h of effort). The goal is enough signal to decide, not a complete build.
• The output is a writeup, not a PR. Any code is throwaway prototype used to learn — it does not get merged. Mark prototype branches clearly and don't open a PR-to-trunk from them.
• End with a recommendation and concrete next steps (usually: tickets to create, or a "don't do this" with the reason).
• Be honest about what you couldn't verify. Lead with the verdict, back it with evidence, and mark anything you can't support with file:line (or a run/probe result) as unverifiable — never pad a recommendation with confidence you didn't earn.
• Pin the codebase state. Record the commit SHA you investigated against (git rev-parse HEAD) plus the date, so the recommendation is reproducible and its staleness is obvious once the trunk moves on.

Arguments

The user invoked this with: $ARGUMENTS

What to do

If no question was given (empty $ARGUMENTS)

Ask the user for the spike question and, ideally, what decision it unblocks. A good spike question is specific and answerable ("Can we stream logs over SSE without exceeding the gateway idle timeout?"), not open-ended ("look into logging"). Confirm the time-box before starting.

If the user gave a question (or create <QUESTION>)

1. Frame the spike. Restate it as:

   • Question — the one thing this spike answers.
   • Decision it unblocks — what the team does differently based on the answer.
   • Time-box — effort budget (default ~4h; confirm with the user).
   • Done-when — the specific signal that ends the spike (e.g. "we know whether approach A is viable and roughly how many tickets it implies").

2. Optionally create a tracking ticket so the work is visible — only if tracker.provider is not none. Skip this step entirely when the tracker is none.

   • For linear: mcp__claude_ai_Linear__save_issue, using tracker.team and tracker.project from the profile.
   • For github: open a tracking issue with gh issue create.
   • title: prefix with Spike: ("Spike: SSE streaming feasibility")
   • state: "Todo" / backlog
   • labels: add a spike/research label if one exists
   • description: the Question / Decision / Time-box / Done-when frame above.
   • Do this when the spike is non-trivial or others need visibility; skip for a quick inline investigation.

3. Investigate. First pin the codebase: capture git rev-parse HEAD + today's date for the findings header (all code-grounded claims are "as of" this SHA). Then run research in parallel — this is fan-out work:

   • Spawn Explore agents to map how the relevant code works today (start with the default source scope from .rig/config.json (sourceScope[0]), then any infra/adjacent packages) and find prior art.
   • Spawn the Plan or architect agent (the latter mapped through agents.architect) to sketch candidate approaches and their trade-offs.
   • Force a structured return from each fan-out agent so findings stay comparable and evidence-backed — e.g. { finding, evidence: [{file:line, quote}], confidence: high|med|low } from explorers, and { approach, buildable: yes|no|with-caveats, files_to_touch, effort: S|M|L, risks } from the planner.
   • WebFetch / WebSearch for unfamiliar APIs, library docs, or version constraints — read the docs before guessing semantics (guessing at API behavior has cost real PRs).
   • If a prototype is needed to learn, build the smallest throwaway one. Keep it on a clearly-named scratch branch; do not open a PR to the trunk.

4. Verify the risky assumptions. Don't stop at "this looks possible." Decompose the recommendation into the discrete claims it depends on (a timeout holds, an API supports X, a migration is reversible, the current code does Y), then prove each one — run the probe, hit the endpoint, read the code. Give every claim an explicit verdict with evidence:

   Claim	Verdict	Evidence	Confidence
   …	confirmed / refuted / partially-true / unverifiable	file:line or probe result	high/med/low

   Mark anything you genuinely couldn't check as unverifiable rather than guessing — an honest gap is more useful than a padded verdict, and it becomes an open question below.

5. Write the findings. Produce a concise writeup with these sections:

   • Header — the question under test, the time-box, and the pinned codebase state (SHA + date) the claims were checked against.

   • Question & answer — lead with the verdict (Yes / No / It depends, and the one-line why).

   • What was investigated — what you read, ran, and prototyped.

   • Findings — the per-claim verdict table from step 4 (evidence + confidence), making explicit what you verified vs. left unverifiable.

   • Options & trade-offs — a table when there's more than one path:

     Option	Effort	Risk	Notes

   • Recommendation — the path you'd take and why.

   • Next steps — concrete follow-up tickets (titles + one-liners), or an explicit "do not pursue, because …".

   • Open questions — anything still unknown that a later spike or the implementation would need to resolve.

   If a tracking ticket was created in step 2, post the writeup back to it (mcp__claude_ai_Linear__save_comment for Linear, gh issue comment for GitHub). Surface it in chat regardless.

6. Hand off. Based on the recommendation, point the user at the right next step:

   • Clear single path → implement a single new ticket.
   • Several independent pieces → plan a sprint of independent tickets.
   • Interleaved pieces with a shared runtime contract → plan an epic on a shared integration branch.
   • Not worth doing → say so plainly and close the spike ticket.

   Do not auto-create the implementation tickets or start coding — a spike ends at the recommendation. The user decides whether to proceed.

If the user passed a ticket identifier (e.g. ABC-123)

Only applicable when tracker.provider is not none.

1. Fetch it (mcp__claude_ai_Linear__get_issue for Linear, gh issue view for GitHub) to read the spike's framing.
2. Run steps 3–6 above against that ticket, posting the findings back as a comment and moving it to the appropriate state when done.