From bishx
Executes multi-agent research pipeline on any topic with Scout, Investigators, Deep Diver, Verifier, Synthesizer, and Critic reviews to produce verified, sourced reports.
npx claudepluginhub bish-x/claude-bishxThis skill uses the workspace's default tool permissions.
⛔ MANDATORY EXECUTION PROTOCOL — READ BEFORE ANYTHING ELSE ⛔
Conducts AI-powered deep research on any topic via triggers like '/deep-research [topic]' or 'deep research on [topic]'. Uses interactive AskUserQuestion for focus, output, and audience selection.
Conducts deep web research with parallel agents, multi-wave exploration for gaps, and structured synthesis. Activates for investigating topics, comparing options, best practices, or comprehensive web info.
Guides agents through structured research phases: planning queries, multi-query execution, source analysis, and synthesis for comprehensive investigations or reports.
Share bugs, ideas, or general feedback.
⛔ MANDATORY EXECUTION PROTOCOL — READ BEFORE ANYTHING ELSE ⛔
You MUST execute the full pipeline below. Do NOT:
You are a CONDUCTOR, not a performer. Your ONLY job is:
FORBIDDEN ACTIONS for the orchestrator:
If you catch yourself reading files to "understand the topic" — STOP. That's the Scout's job. If you catch yourself analyzing content — STOP. That's the Investigator's job. If you catch yourself writing conclusions — STOP. That's the Synthesizer's job. If you catch yourself editing REPORT.md — STOP. That's the Synthesizer's job.
THE PIPELINE MUST RUN. NO EXCEPTIONS. NO SHORTCUTS.
When Phase 7 is complete and REPORT.md exists:
/bishx:research <topic text>
/bishx:research <topic text>, N reviews
/bishx:research <topic text>, N iterations
/Users/..., ./src, ~/project) → enables LOCAL modeThese principles guide EVERY phase of the pipeline. They are non-negotiable.
Apply these to ANY topic, regardless of domain:
Duration: ~10 seconds
.bishx-research/{YYYY-MM-DD_HH-MM}/
mkdir -p {session_dir}/findings {session_dir}/reviews
5a. Ensure .gitignore covers research artifacts (create if not exists):
# Add .bishx-research/ to .gitignore if in a git repo and not already ignored
if [ -d .git ] && ! grep -q '.bishx-research' .gitignore 2>/dev/null; then
echo '.bishx-research/' >> .gitignore
fi
{session_dir}/SCOPE.md:
# Research Scope
## Topic
[Original user text]
## Resource Type
[LOCAL / WEB / HYBRID]
## Domain
[SOFTWARE / ACADEMIC / NARRATIVE / FEASIBILITY / GENERAL]
## Iteration Override
[N or "auto"]
## Session
[Full path to session directory]
## Paths Detected
[List of paths found in topic, or "none"]
🔍 Research: "{topic}"
📁 Session: {session_dir}
🔧 Mode: {resource_type} | Domain: {domain}
Duration: ~60-90 seconds
Agent: bishx:research-scout (Opus)
Spawn Scout agent:
Agent(
subagent_type="bishx:research-scout",
mode="bypassPermissions",
prompt="Read {session_dir}/SCOPE.md. Perform reconnaissance on this topic. Write your report to {session_dir}/RECON.md. Follow your agent protocol exactly."
)
After Scout completes:
{session_dir}/RECON.mditeration_override ?? recommended_iterations🗺️ Recon complete: {complexity} topic
👥 Perspectives: {list}
🔬 Investigators: {N} | Deep Diver: {yes/no}
🔄 Review iterations: {N}
Quick sanity check on Scout output (5 seconds):
Duration: ~15-20 seconds
Generate Research Questions based on RECON.md:
{session_dir}/QUESTIONS.md:
# Research Questions
## Coverage Matrix
| RQ# | Question | Lens | Perspective | Priority | Assigned To | Status |
|-----|----------|------|-------------|----------|-------------|--------|
| RQ-1 | ... | WHAT | Practitioner | BLOCKING | investigator-1 | PENDING |
| RQ-2 | ... | HOW | Critic | IMPORTANT | investigator-2 | PENDING |
...
## Assignment
### Investigator 1 — Perspective: [name]
- RQ-1: [question]
- RQ-4: [question]
- RQ-7: [question]
### Investigator 2 — Perspective: [name]
...
📋 {N} research questions across {M} perspectives
🔬 Starting investigation (Wave 1: {N} agents parallel)...
Duration: ~2-4 minutes
Agent: bishx:research-investigator (Sonnet) × 3-5
Spawn ALL investigators in PARALLEL (single message, multiple Agent calls):
For each investigator assignment in QUESTIONS.md:
Agent(
subagent_type="bishx:research-investigator",
mode="bypassPermissions",
prompt="
You are Investigator {N}, perspective: {perspective_name}.
Your assigned Research Questions:
{RQ list with full text}
Resource type: {LOCAL/WEB/HYBRID}
Domain: {domain from SCOPE.md}
Session directory: {session_dir}
Read {session_dir}/SCOPE.md for topic boundaries and domain type.
Read {session_dir}/RECON.md for landscape context, key sources, and pitfalls.
Adapt your investigation to the domain:
- SOFTWARE: prioritize code, docs, GitHub, lock files
- ACADEMIC: prioritize peer-reviewed papers, textbooks, university sources
- NARRATIVE: prioritize primary works (films, books), critical analyses, author interviews
- FEASIBILITY: prioritize benchmarks, case studies, technical constraints
- GENERAL: use your best judgment based on the topic
Write your findings to: {session_dir}/findings/investigator-{N}.md
Follow your Embedded Skepticism Protocol for EVERY finding.
"
)
CRITICAL: Launch ALL investigators in a SINGLE message to ensure parallel execution.
After all complete:
findings/investigator-{N}.md✅ Wave 1 complete: {N} investigators, {M} findings
📊 Confidence: {H} HIGH, {M} MEDIUM, {L} LOW
⚡ Contradictions: {N} | Gaps: {N}
Duration: ~2-3 minutes (skipped if not needed)
Agent: bishx:research-deep-diver (Opus) × 1-2
Run ONLY IF Scout recommended Deep Diver (complexity=COMPLEX or significant contradictions/gaps found in Wave 1).
Agent(
subagent_type="bishx:research-deep-diver",
mode="bypassPermissions",
prompt="
Read ALL investigation findings in {session_dir}/findings/investigator-*.md
Read {session_dir}/RECON.md for context.
Read {session_dir}/QUESTIONS.md for RQ coverage.
Focus on:
1. Contradictions found: {list from Wave 1}
2. Critical LOW-confidence findings: {list}
3. Complex areas needing depth: {list from RECON.md}
Write to: {session_dir}/findings/deep-diver-1.md
"
)
After completion:
🔎 Deep dive complete: {N} contradictions resolved, {M} findings deepened
Duration: ~2-3 minutes
Agent: bishx:research-verifier (Opus)
Agent(
subagent_type="bishx:research-verifier",
mode="bypassPermissions",
prompt="
Verify ALL findings in {session_dir}/findings/ (all investigator-*.md and deep-diver-*.md files).
Read {session_dir}/SCOPE.md for topic domain — adapt staleness rules to domain.
Cross-reference with {session_dir}/RECON.md pitfall warnings.
Read {session_dir}/QUESTIONS.md for RQ priorities (BLOCKING/IMPORTANT/ENRICHING).
Write your verification report to: {session_dir}/VERIFIED.md
Check EVERY HIGH confidence claim exhaustively.
Check MEDIUM claims in BLOCKING RQs (use QUESTIONS.md to identify which RQs are BLOCKING).
Sample 50% of MEDIUM claims in IMPORTANT RQs.
Perform the pitfall cross-check.
"
)
After completion:
VERIFIED.md✓ Verification: {N} claims checked, {%} verified, {M} mirages caught
📝 Starting synthesis...
Duration: ~1-2 minutes
Agent: bishx:research-synthesizer (Opus)
Agent(
subagent_type="bishx:research-synthesizer",
mode="bypassPermissions",
prompt="
Create the initial research report draft.
Read ALL of these files:
- {session_dir}/SCOPE.md (topic boundaries and resource type)
- {session_dir}/RECON.md (landscape, pitfalls, perspectives)
- {session_dir}/QUESTIONS.md (RQs and coverage matrix)
- ALL files in {session_dir}/findings/ (all investigator and deep-diver reports)
- {session_dir}/VERIFIED.md (verification results, mirages, confidence adjustments)
Write DRAFT to: {session_dir}/DRAFT.md
Follow your Synthesis Protocol exactly. Every claim must have a source reference.
Exclude all mirages from VERIFIED.md. Use correct hedging language per confidence level.
Reference RECON.md pitfalls to ensure you don't introduce pitfall-related errors in synthesis.
"
)
After completion:
📝 Draft complete. Starting critical review ({N} iterations)...
Duration: ~3-4 minutes per iteration
Agents: bishx:research-critic (Opus, persistent) + targeted investigators + verifier
FOR i = 1 TO max_iterations:
# Step 1: Critic reviews the draft
Agent(
subagent_type="bishx:research-critic",
mode="bypassPermissions",
prompt="
This is review iteration {i} of {max_iterations}.
Read and critically review:
- {session_dir}/SCOPE.md (topic and domain)
- {session_dir}/DRAFT.md (current draft)
- {session_dir}/VERIFIED.md
- {session_dir}/QUESTIONS.md
- {session_dir}/RECON.md
- ALL findings in {session_dir}/findings/
{if i > 1: - Your prior review: {session_dir}/reviews/review-{i-1}.md}
Write your review to: {session_dir}/reviews/review-{i}.md
Apply all 5 review levels. Score on 4 dimensions.
{if i > 1: First verify fixes from prior iteration, then find NEW issues.}
"
)
# Step 2: Check verdict
Read reviews/review-{i}.md
Extract: verdict, scores, issues, re-investigation requests
Output to user:
🔎 Review {i}/{max}: {verdict}
📊 Scores: Completeness {C}/10, Accuracy {A}/10, Depth {D}/10, Balance {B}/10 → Overall {O}/10
{if NEEDS_WORK: 🔧 Issues: {N_critical} critical, {N_important} important, {N_minor} minor}
IF verdict == "APPROVED":
Output: ✅ Approved on iteration {i}!
BREAK → Phase 7
IF i == max_iterations AND verdict == "NEEDS_WORK":
Output: ⚠️ Max iterations reached. Proceeding with best version (score: {O}/10).
BREAK → Phase 7
# Step 3: Handle re-investigation requests (if any CRITICAL/IMPORTANT issues)
IF re-investigation requests exist:
# Spawn targeted investigators on OPUS for specific issues (parallel)
# NOTE: Re-investigation uses model="opus" override — Sonnet is too shallow for targeted fixes.
For each RE-{N} request:
Agent(
subagent_type="bishx:research-investigator",
model="opus",
mode="bypassPermissions",
prompt="
TARGETED RE-INVESTIGATION for review iteration {i}.
Task: {RE-N request text}
Context: This was flagged by the Critic because: {reason}
Read {session_dir}/RECON.md for context.
Read relevant prior findings in {session_dir}/findings/ for what was already covered.
Append your findings to: {session_dir}/findings/investigator-re-{i}-{N}.md
Focus ONLY on this specific request. Be thorough and deep — you are fixing a gap
that a first-pass investigator missed. Use all available tools.
"
)
# Re-verify new findings (write to SEPARATE file to preserve immutability of original VERIFIED.md)
Agent(
subagent_type="bishx:research-verifier",
mode="bypassPermissions",
prompt="
TARGETED RE-VERIFICATION for review iteration {i}.
Read the original verification: {session_dir}/VERIFIED.md
Verify ONLY the new findings in: {session_dir}/findings/investigator-re-{i}-*.md
Read {session_dir}/QUESTIONS.md for RQ priorities.
Write results to: {session_dir}/reviews/re-verified-{i}.md
Do NOT modify the original VERIFIED.md — it is immutable.
"
)
# Step 4: Update draft
Agent(
subagent_type="bishx:research-synthesizer",
mode="bypassPermissions",
prompt="
UPDATE the research draft based on review feedback.
Read:
- {session_dir}/SCOPE.md (topic boundaries)
- {session_dir}/QUESTIONS.md (RQ coverage matrix)
- {session_dir}/DRAFT.md (current draft)
- {session_dir}/VERIFIED.md (original verification)
- {session_dir}/reviews/review-{i}.md (Critic's feedback)
- {session_dir}/reviews/re-verified-{i}.md (re-verification results, if exists)
- Any new findings: {session_dir}/findings/investigator-re-{i}-*.md
Address EVERY CRITICAL and IMPORTANT issue from the review.
Update {session_dir}/DRAFT.md in place.
Add revision note at the end.
"
)
Output: 📝 Draft updated. {if i < max_iterations: Starting review {i+1}...}
END FOR
Duration: ~1 minute
Agent: bishx:research-synthesizer (Opus)
Agent(
subagent_type="bishx:research-synthesizer",
mode="bypassPermissions",
prompt="
Create the FINAL research report.
Read ALL of these files:
- {session_dir}/SCOPE.md (original topic and boundaries)
- {session_dir}/QUESTIONS.md (RQs and coverage matrix)
- ALL files in {session_dir}/findings/ (all investigator and deep-diver reports)
- {session_dir}/VERIFIED.md (verification results, mirages, confidence adjustments)
- {session_dir}/DRAFT.md (latest draft version)
- {session_dir}/reviews/ (all review files for quality metadata)
Write the final report to: {session_dir}/REPORT.md
This is the final version. You have access to ALL source materials.
Polish the language, ensure all sources are properly cited,
add the Research Quality section with final scores from the last review,
fill in Scope & Methodology accurately from SCOPE.md and QUESTIONS.md,
and ensure the report is complete and self-contained.
The report must be the DEFINITIVE answer to the user's original question.
"
)
After completion:
{session_dir}/REPORT.md exists (Glob check). If not — agent fallback: write agent's returned text.{session_dir}/REPORT.md
---
📄 Full report: {session_dir}/REPORT.md
📊 Quality: {overall_score}/10 | Verified: {%}
🔄 Reviews: {iterations_used}/{max_iterations}
⏱️ Duration: {total_time}
When user does NOT specify iteration count:
| Scout Complexity | Default Iterations | Early Exit |
|---|---|---|
| SIMPLE | 1 | If APPROVED → done |
| MODERATE | 2 | If APPROVED on iter 1 → done |
| COMPLEX | 3 | If APPROVED on any iter → done |
If Critic gives APPROVED before max iterations → early exit (save time and cost). If Critic score < 6/10 after last iteration → extend by 1 extra iteration (recovery attempt).
| Error | Detection | Action |
|---|---|---|
| Agent returns empty output | Output file < 100 bytes | Re-run agent ONCE with: "Previous run produced empty output. Retry." |
| Agent output missing required sections | Section header grep | Re-run agent ONCE with: "Missing required section: {name}" |
| Session directory doesn't exist | Glob check | Create it, log warning |
| findings/ directory empty after Wave 1 | File count check | STOP — report error to user, likely tool access issue |
| VERIFIED.md shows >50% mirages | Mirage percentage | Add 1 extra review iteration automatically |
| All investigators return same perspective | Diversity check | Log warning in report, note limited perspective coverage |
| Agent timeout (>10 min, hung web requests) | No completion after 10 min | Skip agent, log gap, continue pipeline with available findings |
| Tool access denied (agent tries tool not in list) | Tool error in agent output | Re-run with corrected prompt, or skip and log |
| Agent partial output (crashed mid-generation) | Output file exists but missing closing sections | Treat as complete for available content, note partial in VERIFIED.md |
| Model safety refusal | Agent returns refusal instead of findings | Log refusal reason, skip sub-topic, note in Gaps section of report |
| Zero web results for all investigators | All findings files have [NO SOURCE FOUND] only | Switch to alternative search strategy or report as research gap |
| Agent doesn't write file (returns text to orchestrator) | Expected output file not found after agent completes | Orchestrator MUST write the agent's returned text to the expected file path, then continue |
Throughout the pipeline, output concise status updates:
🔍 Research: "topic text"
📁 Session: .bishx-research/2026-04-10_14-30/
🔧 Mode: WEB | Domain: GENERAL
🗺️ Recon complete: MODERATE topic
👥 Perspectives: Practitioner, Critic, Newcomer, Historian
🔬 Investigators: 4 | Deep Diver: no
🔄 Review iterations: 2
📋 12 research questions across 4 perspectives
🔬 Starting investigation (Wave 1: 4 agents parallel)...
✅ Wave 1 complete: 4 investigators, 31 findings
📊 Confidence: 12 HIGH, 14 MEDIUM, 5 LOW
⚡ Contradictions: 2 | Gaps: 3
✓ Verification: 31 claims checked, 87% verified, 2 mirages caught
📝 Starting synthesis...
📝 Draft complete. Starting critical review (2 iterations)...
🔎 Review 1/2: NEEDS_WORK
📊 Scores: Completeness 7/10, Accuracy 8/10, Depth 6/10, Balance 7/10 → Overall 7/10
🔧 Issues: 1 critical, 3 important, 2 minor
📝 Draft updated. Starting review 2/2...
🔎 Review 2/2: APPROVED
📊 Scores: Completeness 8/10, Accuracy 9/10, Depth 8/10, Balance 8/10 → Overall 8.3/10
✅ Approved on iteration 2!
[FULL REPORT OUTPUT]
---
📄 Full report: .bishx-research/2026-04-10_14-30/REPORT.md
📊 Quality: 8.3/10 | Verified: 87%
🔄 Reviews: 2/2
⏱️ Duration: ~14 min