viper-2-investigate

name	viper-2-investigate
description	VIPER phase 2 — Investigate. Aggressive truth-finding against vision.md or the user's prompt when Vision was skipped. Spawn investigator subagents for independent sub-questions, build a shared vocabulary, eliminate assumptions, then write investigation.md.

viper-2-investigate

You are running the Investigate phase of VIPER. When Vision ran, it gave you a converged direction. When Vision was skipped, the user's prompt is the direction — you still need to surface every uncertainty around it. Your job is to find what's actually in the codebase, what external dependencies behave like, what vocabulary the team needs to agree on — and write the answers down. The Plan phase that follows must be able to reason about scope without re-discovering anything.

You may write files (only investigation.md), spawn subagents for independent sub-questions, and use unrestricted research tools. You loop on AskUserQuestion until the user has no remaining ambiguity.

---

Boot sequence

1. Probe MCP: call mcp__viper__ping. On success, prefer MCP tools (mcp__viper__*). On failure, shell out to viper.
2. Locate the idea. If the user invoked the skill with a slug or number, use it. Otherwise call mcp__viper__list_ideas (or viper list) and ask via AskUserQuestion which idea to investigate (max 4 options). If no ideas exist, call mcp__viper__create_idea with phases: ["investigation", "plan", "execution", "review"] (Vision omitted) and use the returned slug.
   • Resolve dirName (required). Idea directories are always numbered: .viper/NNN-<slug>/ (e.g. 001-multi-agent-harness). The bare slug (multi-agent-harness) is not a valid path. Get dirName from viper list / MCP list output, from the idea: frontmatter field in phase docs, or from the path printed by viper new. Never guess or strip the numeric prefix.
3. Check Vision status via mcp__viper__get_phase for vision:
   • vision.status is complete — normal path. Read vision.md as upstream context.
   • vision.md exists but status is not complete — ask via AskUserQuestion with header "Vision incomplete":
     • "Finish Vision first" — tell the user to /clear + /viper-1-vision, then stop
     • "Skip Vision and start Investigate anyway" — warn that ideation/brainstorming will not happen; the user's current prompt becomes the direction; proceed only on this choice
     • "Other"
   • vision.md does not exist (get_phase returns not-found / missing) — ask via AskUserQuestion with header "No Vision phase":
     • "Proceed without Vision — start Investigate from my prompt" — confirm they understand ideation is skipped
     • "Run Vision first" — suggest /viper-1-vision or re-scaffold with Vision included, then stop
     • "Other"
4. Ensure investigation.md exists:
   • If Vision is complete: call mcp__viper__advance_phase with from: vision, to: investigation (or continue editing if it already exists).
   • If Vision was skipped: call mcp__viper__ensure_phase with phase: investigation. Do not call advance_phase from vision — there is no complete upstream to advance from.

---

Step 1 — Extract the open questions

When vision.md is complete, start from its Open Questions for Next Phase section. Add to that:

• Anything in Selected Direction that names a technology / library / API you haven't verified
• Any decision in Key Decisions that depends on a fact you can't currently cite
• Any term used in vision.md that doesn't have an agreed definition yet

When Vision was skipped, derive open questions from the user's prompt instead:

• What problem are they trying to solve? What does "done" look like?
• Any technology / library / API they named that you haven't verified
• Any constraint they implied (performance, compatibility, timeline) that needs a fact check
• Any term in the prompt that doesn't have an agreed definition yet

Group questions into:

• Codebase questions — answered by reading this repo (architecture, conventions, existing patterns, currently-imported libraries)
• External questions — answered by researching APIs, libraries, standards, prior art outside this repo
• Human questions — only the user can answer (priorities, constraints, taste calls)

Don't ask the human anything yet. First fan out on the things you can answer yourself.

---

Step 2 — Spawn investigators in parallel

For each independent codebase or external question, spawn one viper-investigator subagent via the Agent tool with subagent_type: viper-investigator. Issue all Agent calls in a single message so they run in parallel.

Pass each investigator:

• The direction (vision summary if Vision ran; otherwise the user's prompt / your distilled problem statement)
• The single concrete question to investigate
• dirName — the full idea directory name including numeric prefix (e.g. 001-multi-agent-harness). Spikes go under .viper/<dirName>/spikes/<question-slug>/, never .viper/<slug-without-prefix>/.
• Hard rules: investigators may write only inside .viper/<dirName>/spikes/<question-slug>/ (throwaway experiments) — no edits to the real codebase. Return structured markdown (Answer / Evidence / Open follow-ups).
• Spike permission: if the question is technical and cheap to verify by running code (e.g. "does library X handle case Y", "what's the actual shape of API response Z"), encourage the investigator to build a 20-line spike under its spikes/ subdir, run it, and quote the result as evidence. Spikes are stronger than speculation.

Independent means the answers don't depend on each other. If question B is "what does question A imply for our design?" — don't parallelize; sequence them.

Wait for all subagents to return before moving on.

---

Step 3 — Recap findings in narrative

Just like Vision's recap step, write a narrative recap of every investigator's findings before asking anything. The user needs the full picture before fielding clarifying questions.

For each question:

• Question N: <the question, verbatim>
  • Answer: 1-2 sentences
  • Key evidence: file paths, version numbers, links — keep this brief; the full evidence is in your subagent transcripts
  • Follow-ups raised: anything the investigator flagged as a new question

Then list any new questions the investigators surfaced that weren't on your original list. These get added to the loop.

---

Step 4 — Ask the human questions

Pull from your "Human questions" pile (Step 1) plus the new ones from Step 3. Ask them via AskUserQuestion, one batch per question (single-select, max 4 options each — if more, list extras in your message text and let the user pick "Other" with a reference).

For each user answer, write the answer + the user's reasoning into your working notes. Reasoning is as valuable as the answer — it tells Plan and Execute why a constraint exists.

If the user's answer raises new codebase or external questions, loop back to Step 2.

---

Step 5 — Cross-pollinate research threads

When the question pile is almost empty, always ask one more AskUserQuestion:

"Any threads worth pulling on further before we lock investigation?"

Options:

1. "Investigation is complete — let's write it up"
2. "Dig deeper into "
3. "Reconsider in light of what we found"
4. "Other" (free text)

This is the explicit moment to rescue half-explored ideas, not the implicit one. Don't skip it.

---

Step 6 — Write investigation.md

Fill in the required sections via Edit:

• Vocabulary — a glossary of terms the user, you, and the next-phase agent all need to share. Each entry is **Term** — definition. Include any term that was clarified during the loop, even if the term seems "obvious" now — it wasn't obvious before the loop.
• Current State — what exists in the codebase today that's relevant to the idea. Cite paths and behaviors. No proposals.
• Constraints & Dependencies — facts that the Plan phase cannot violate: library versions, deployment targets, performance budgets, API contracts, stakeholder constraints.
• External Dependencies — third-party libs / APIs / standards relevant to this idea, with versions and any quirks the investigators surfaced.
• Risks & Unknowns — things you could not resolve. Each entry: the risk + the impact if it materializes + the trigger that would force a re-investigation.
• Recommendations for Plan — concrete steers for the Plan phase. Don't write the plan; suggest scopes, slicings, and ordering hints. Flag where the spec-tool handoff (OpenSpec/SpecKit) should be considered.

Refresh the updated timestamp in frontmatter. Leave status: draft.

---

Step 7 — Close out

1. Show the user the path to investigation.md.
2. Ask via AskUserQuestion whether to mark status: complete now or leave it as draft for review.
3. On confirmation, call mcp__viper__set_status to flip the status.
4. Suggest the next step: /clear and then /viper-3-plan.

---

Hard rules

• Investigation is required; Vision is optional. Never refuse to run solely because Vision is missing — but always confirm with the user before skipping an incomplete or absent Vision phase (Boot sequence step 3).
• You may write only investigation.md. No code changes, no doc changes outside the idea dir.
• Spawn subagents for parallel sub-questions. Don't serialize work that can fan out.
• Never assume. When in doubt, ask via AskUserQuestion or spawn an investigator. Recording an uncertainty as a Risk is also fine — but don't paper over it.
• Spikes beat speculation. If a question has a cheap empirical answer (a 20-line script, a single API call, a tiny test), prefer asking an investigator to run a spike over reasoning about it. Spikes live under .viper/<dirName>/spikes/ (gitignored) and are throwaway by design. Always pass the full dirName (e.g. 001-foo), not the bare slug.
• Always run Step 5. The cross-pollination / depth check is non-optional, even if Step 4 seemed conclusive.
• Vocabulary is mandatory. Even one entry. If you can't write a single Vocabulary entry, the investigation didn't surface enough.