/craft-research-verify

name: research-verify
description: "Verify existing research findings against independent primary sources. Upgrades confidence from 'sources agree' to 'independently verified.'"
argument-hint: "[topic-slug]"

Research Verify

Verify existing research by challenging claims against independent primary sources. This is NOT "go deeper" - it's adversarial validation. The goal is to confirm or refute what the research already says.

Project Root

Use `$CRAFT_PROJECT_ROOT` (set at session start) as the base path for all `.craft/` references. If not set, resolve by walking up from PWD to find the nearest `.craft/.global-state`.

Set `PROJECT` to `${CRAFT_PROJECT_ROOT:-.}`.

Flow

Step 1: Select Topic

**If args contain a topic slug** that matches a folder in `$PROJECT/.craft/research/`: -> Use that topic. Jump to **Step 2**.

**If no args or no match:** Use **Glob** with pattern `$PROJECT/.craft/research/*/_plan.md` to find all topics.

For each, use **Read** with `limit: 15` to get frontmatter. Only show topics with `status: complete`.

Use **AskUserQuestion** to pick a topic.

Step 2: Extract Findings

Read the topic's `_plan.md` in full.

Use **Glob** to find all branch files: `$PROJECT/.craft/research/{topic-slug}/[0-9]*.md`

For each branch file, use **Read** to extract:

• All `### Finding N: {title}` entries
• Their `**Confidence:**` level (HIGH/MEDIUM/LOW)
• Their `**Sources:**` references

Build a findings list:

| # | Branch | Finding | Confidence | Sources |
|---|--------|---------|------------|---------|
| 1 | 02-claude-code-ecosystem | PostToolUse payload uses tool_response not tool_output | HIGH | [1][2] |
| 2 | 02-claude-code-ecosystem | AskUserQuestion answers live in tool_input | HIGH | [1][2][3] |
| 3 | 01-multi-agent-frameworks | OpenHands dominates at 70.9K stars | MEDIUM | [1] |
...

Also check for existing `verification-*.md` files - mark already-verified findings so the user doesn't re-verify them.

Step 3: Choose Verification Mode

Present the findings table to the user, then ask how they want to verify.

Use **AskUserQuestion**:

question: "How should I verify these {N} findings?"
header: "Verification Mode"
options:
  - label: "Source verification"
    description: "Check claims against independent primary sources (verifier agents)"
  - label: "Practitioner review"
    description: "Challenge claims from practical experience - catches 'true in docs, wrong in practice'"
  - label: "Both passes"
    description: "Source verification first, then practitioner review on the results"
  - label: "Cancel"
    description: "Back out"

**If "Source verification"** -> Jump to **Step 3b** (select findings), then **Step 4** (verifiers). **If "Practitioner review"** -> Jump to **Step 4b** (practitioner reviewer). **If "Both passes"** -> Jump to **Step 3b** (select findings), then **Step 4** (verifiers), then **Step 4b** (practitioner reviewer on results). **If "Cancel"** -> End. **If custom text** -> Interpret.

Step 3b: Select Findings (for source verification)

Use **AskUserQuestion**:

question: "Which findings should I verify against sources?"
header: "Findings"
options:
  - label: "All high-confidence"
    description: "Verify all HIGH confidence findings ({N} findings) - these are most dangerous if wrong"
  - label: "All unverified"
    description: "Verify everything not yet verified ({N} findings)"
  - label: "Pick specific findings"
    description: "Choose which ones to verify"

**If "All high-confidence"** -> Filter to HIGH confidence findings. Jump to **Step 4**. **If "All unverified"** -> Filter to findings without existing verification files. Jump to **Step 4**. **If "Pick specific"** -> Show numbered list, let user pick by number or description. Jump to **Step 4**. **If custom text** -> Interpret (e.g., "verify findings 1, 3, and 7", "verify everything from branch 02").

Step 4: Spawn Verification Researchers

For each selected finding, spawn a **researcher agent** in parallel:

subagent_type: "craft:verifier"
description: "Verify: {short finding title}"
prompt: |
  ## Your Assignment

  **Claim to verify:** "{exact finding text from branch file}"
  **Original sources cited:** {list of sources from the finding}
  **Branch file:** {path to branch file} (Finding {N})
  **Write your verification to:** {$PROJECT/.craft/research/{topic-slug}/verification-{finding-slug}.md}

**Launch ALL verification agents simultaneously.**

Step 4b: Practitioner Review

Spawn a single **practitioner-reviewer** agent. This agent reads all claims (or all verified claims if running after Step 4) and challenges them from practical experience.

subagent_type: "craft:practitioner-reviewer"
description: "Practitioner review: {topic}"
prompt: |
  ## Your Assignment

  **Topic:** {topic name}
  **Research folder:** {$PROJECT/.craft/research/{topic-slug}/}
  **Branch files to read:** {list of branch file paths}
  **Verification files (if any):** {list of verification file paths, or "none - this is the first pass"}
  **Write your review to:** {$PROJECT/.craft/research/{topic-slug}/practitioner-review.md}

  Read all branch files and any verification files. Review every claim from a
  practitioner perspective. Flag anything that doesn't match how these tools
  actually work in practice.

After the agent completes, read `practitioner-review.md` frontmatter to get flag counts.

**If running in "Both passes" mode:** Update any verification files where the practitioner flagged a CONFIRMED claim - add `practitioner_flag: true` to the verification file's frontmatter. These claims show as FLAGGED_BY_PRACTITIONER in the results table.

Step 5: Verification File Format

Each verification agent writes using this format:

---
topic: "{topic-slug}"
branch: "{branch-file-name}"
finding: "Finding {N}"
finding_title: "{finding title}"
verdict: CONFIRMED | REFUTED | PARTIALLY_TRUE | UNVERIFIABLE
original_confidence: {HIGH|MED