feat(me): improve external research workflow

[baleen37]

Summary

• focus me:research on external source discovery and verification
• route normal research through one compact me:researcher
• prefer owning and primary sources, opened source bodies, bounded stopping, and explicit uncertainty
• fall back to direct parent research when delegation is unavailable, while loading the same read-only evidence contract
• keep exact-source reads safe by loading the researcher contract before consuming retrieved content

Why

The previous research skill mixed local investigation with external research
and later became unusable when mandatory subagent delegation hit the agent
thread limit. Exact-source reads also did not explicitly load the shared
evidence and prompt-injection rules.

This keeps the workflow small and follows OpenAI's current guidance: use clear
specialized agent boundaries, start with minimal orchestration, evaluate
behavior iteratively, and treat retrieved text as untrusted data.

Impact

• external research returns compact answers with claim-bearing sources and
  material gaps
• raw search traces and discarded sources stay out of the final answer
• delegation failures no longer block read-only research
• codebase exploration and local bug investigation are rejected as out of
  scope

Verification

• focused Bats: 20/20
• unit Bats: 65/65
• instruction budget: 567/580 words
• RED: mandatory delegation blocked 2/2 agents
• GREEN: comparison 5/5, required variations 3/3, conflict case 1/1
• exact-source RED/GREEN trace confirmed researcher.md is loaded before
  direct reading and retrieved instructions remain untrusted evidence
• independent final review: no Critical, Important, or Minor findings

Summary by CodeRabbit

• New Features

  • Streamlined external research into a focused workflow using a dedicated research specialist.
  • Research requests now return concise answers with inline citations, claim-relevant sources, and material confidence gaps.
  • Added a direct-research fallback when delegation is unavailable or an exact source is provided.
  • Improved handling of source verification, uncertainty, conflicting evidence, and untrusted content.

• Documentation

  • Added implementation and design guidance for the updated research workflow and validation scenarios.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 7a8efb2f-e807-46e3-90d6-865634e7946a

📥 Commits

Reviewing files that changed from the base of the PR and between f906474 and b41259e.

📒 Files selected for processing (5)

• docs/superpowers/plans/2026-07-26-external-research-subagent.md
• docs/superpowers/plans/2026-07-26-research-delegation-fallback.md
• docs/superpowers/specs/2026-07-25-external-research-subagent-design.md
• plugins/me/agents/researcher.md
• plugins/me/skills/research/SKILL.md

---

📝 Walkthrough

Walkthrough

The PR narrows research to external sources, routes discovery through one me:researcher with a direct fallback, and defines read-only evidence and output contracts. Supporting design and implementation plans document model selection, validation scenarios, word budgets, and repository checks.

Changes

External research workflow

Layer / File(s)	Summary
Research contracts and implementation plans docs/superpowers/specs/*, docs/superpowers/plans/*research*	Documents define external-only scope, single-agent delegation, fallback behavior, evidence requirements, output structure, model policy, validation scenarios, and commit checks.
Research skill routing plugins/me/skills/research/SKILL.md	The skill now handles external reference research, delegates source discovery to one me:researcher, supports direct execution fallback, and returns compact answers with claim-bearing sources and material gaps.
Read-only researcher behavior plugins/me/agents/researcher.md	The researcher now discovers and verifies external sources only, applies bounded evidence rules, and emits structured answers, sources, and confidence gaps without search traces.

Estimated code review effort: 2 (Simple) | ~15 minutes

Possibly related PRs

• baleen37/bstack#653: Updates the research skill’s evidence and workflow guidance.
• baleen37/bstack#699: Reworks research routing and the researcher agent contract.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch agent/improve-research-skill

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}