Add a /research skill

CLAUDE.md

@@ -17,17 +17,17 @@ Current version: **2.4.0** (see [CHANGELOG.md](./CHANGELOG.md)).
 ├── plugin/             # The actual plugin shipped to Claude Code
 │   ├── .claude-plugin/
 │   │   └── plugin.json
-│   ├── agents/         # 21 agent definitions (.md with frontmatter)
-│   ├── skills/         # 18 skill directories, each with SKILL.md + references/
+│   ├── agents/         # 22 agent definitions (.md with frontmatter)
+│   ├── skills/         # 19 skill directories, each with SKILL.md + references/
 │   └── references/     # Cross-skill reference files (e.g. yagni-rule.md)
 ├── docs/               # Operator-facing documentation
 │   ├── writing-voice.md   # Voice profile every doc follows
 │   ├── concepts.md
 │   ├── quickstart.md
 │   ├── sizing.md
 │   ├── yagni.md
-│   ├── agents/         # Long-form docs for all 21 agents, plus README
-│   ├── skills/         # Long-form docs for all 18 skills, plus README
+│   ├── agents/         # Long-form docs for all 22 agents, plus README
+│   ├── skills/         # Long-form docs for all 19 skills, plus README
 │   ├── guidance/       # Contributor-facing authoring guidance
 │   └── templates/      # Templates and coverage rule for long-form docs
 └── images/             # Banner and graphics for README
@@ -51,12 +51,12 @@ The plugin is shipped from `plugin/`; documentation lives in `docs/`. Long-form
 
 - **[docs/concepts.md](./docs/concepts.md).** The skill-vs-agent model that runs through the whole plugin. Read once before doing anything else. Every other doc assumes this vocabulary.
 - **[docs/quickstart.md](./docs/quickstart.md).** Four path-based recipes (plan a feature, investigate a bug, review code, set up a project). Use when picking which skill to run for a specific situation.
-- **[docs/sizing.md](./docs/sizing.md).** The small / medium / large dispatch model used by the six swarming skills (`/architectural-analysis`, `/code-review`, `/gap-analysis`, `/iterative-plan-review`, `/plan-a-feature`, `/plan-implementation`). Use when a swarming skill needs to decide team size, or when a user asks what `medium` / `large` mean.
+- **[docs/sizing.md](./docs/sizing.md).** The small / medium / large dispatch model used by the seven swarming skills (`/architectural-analysis`, `/code-review`, `/gap-analysis`, `/iterative-plan-review`, `/plan-a-feature`, `/plan-implementation`, `/research`). Use when a swarming skill needs to decide team size, or when a user asks what `medium` / `large` mean.
 - **[docs/yagni.md](./docs/yagni.md).** The evidence-based "You Aren't Gonna Need It" rule every planning, review, and architecture skill applies before committing items to its artifact. Use when explaining why an item was deferred or rejected from a plan / review / ADR.
 
 ### Skill catalog (`docs/skills/`)
 
-- **[docs/skills/README.md](./docs/skills/README.md).** Index of all 18 skills grouped by purpose (planning, building, investigation, review, discovery, conventions, reporting). Start here when looking for the right slash command.
+- **[docs/skills/README.md](./docs/skills/README.md).** Index of all 19 skills grouped by purpose (planning, building, investigation and research, review, discovery, conventions, reporting). Start here when looking for the right slash command.
 - **[docs/skills/plan-a-feature.md](./docs/skills/plan-a-feature.md).** Spec a feature from scratch through an evidence-based interview that walks the design tree and dispatches specialist reviewers.
 - **[docs/skills/plan-implementation.md](./docs/skills/plan-implementation.md).** Turn a feature specification into an implementation plan through a project-manager-led team conversation.
 - **[docs/skills/plan-a-phased-build.md](./docs/skills/plan-a-phased-build.md).** Split a body of context (gap analysis, PRD, design doc) into a numbered sequence of vertical-slice phases, each independently demoable.
@@ -65,6 +65,7 @@ The plugin is shipped from `plugin/`; documentation lives in `docs/`. Long-form
 - **[docs/skills/tdd.md](./docs/skills/tdd.md).** Drive a feature or behavior through a BDD-framed red-green-refactor loop with an enforced observed-failure gate. The plugin's only execution skill: it writes code, applying coding standards and ADRs in green and refactor.
 - **[docs/skills/issue-triage.md](./docs/skills/issue-triage.md).** Classify a vague issue or bug report, identify missing information, assess severity and reproducibility, and recommend the right next skill.
 - **[docs/skills/investigate.md](./docs/skills/investigate.md).** Evidence-based investigation of bugs, failures, and unexpected behavior, with adversarial validation of the proposed fix.
+- **[docs/skills/research.md](./docs/skills/research.md).** Research an open-ended question (options, prior art, how something works) across the codebase and the open web, ending at an adversarially-validated recommendation. The question-shaped sibling of investigate.
 - **[docs/skills/code-review.md](./docs/skills/code-review.md).** Comprehensive code review of the current branch or specified files. Dispatches a domain-aware roster that scales with sizing.
 - **[docs/skills/gh-pr-review.md](./docs/skills/gh-pr-review.md).** Run `/code-review` against a GitHub PR and post the review as comments after a clarity check.
 - **[docs/skills/architectural-analysis.md](./docs/skills/architectural-analysis.md).** Deep architectural analysis of a module: coupling, data flow, concurrency, risk, and SOLID alignment.
@@ -78,15 +79,15 @@ The plugin is shipped from `plugin/`; documentation lives in `docs/`. Long-form
 
 ### Agent catalog (`docs/agents/`)
 
-- **[docs/agents/README.md](./docs/agents/README.md).** Index of all 21 agents grouped by role (planning, adversarial review, investigation, architecture, testing, gap/content). Start here when looking for the right sub-agent to dispatch directly.
+- **[docs/agents/README.md](./docs/agents/README.md).** Index of all 22 agents grouped by role (planning, adversarial review, investigation, architecture, testing, gap/content). Start here when looking for the right sub-agent to dispatch directly.
 
-Every agent has a long-form doc under `docs/agents/`. The 21 agents:
+Every agent has a long-form doc under `docs/agents/`. The 22 agents:
 
 Planning & facilitation: `project-manager`, `junior-developer`.
 
 Adversarial reviewers: `adversarial-security-analyst`, `adversarial-validator`, `devops-engineer`, `data-engineer`, `information-architect`, `user-experience-designer`.
 
-Investigation & evidence: `evidence-based-investigator`, `codebase-explorer`, `project-scanner`.
+Investigation & evidence: `evidence-based-investigator`, `research-analyst`, `codebase-explorer`, `project-scanner`.
 
 Architecture & risk: `structural-analyst`, `behavioral-analyst`, `concurrency-analyst`, `risk-analyst`, `software-architect`, `system-architect`.
 
@@ -126,4 +127,4 @@ Subdirectories:
 - **Every long-form doc links up.** The first bullet of the "Related Documentation" section always points back to the README at the repo root.
 - **Voice is uniform.** Every doc follows [docs/writing-voice.md](./docs/writing-voice.md). No em-dashes, direct second person, no flattery or hype.
 - **YAGNI applies to docs too.** Don't add speculative sections, for-future-flexibility warnings, or examples for behavior the skill doesn't have. The same evidence rule that gates plan steps gates docs.
-- **Counts to verify when editing indexes.** 21 agents in `plugin/agents/`; 18 skills in `plugin/skills/`; 21 long-form agent docs in `docs/agents/`; 18 long-form skill docs in `docs/skills/`.
+- **Counts to verify when editing indexes.** 22 agents in `plugin/agents/`; 19 skills in `plugin/skills/`; 22 long-form agent docs in `docs/agents/`; 19 long-form skill docs in `docs/skills/`.

README.md

@@ -15,9 +15,9 @@ Read [Concepts](./docs/concepts.md) for the skill-and-agent model that runs thro
 ## Which path are you on?
 
 - **New to han?** → Start with [Concepts](./docs/concepts.md), then the [Quickstart](./docs/quickstart.md).
-- **Looking for a specific skill?** → [Skills Index](./docs/skills/README.md). 18 skills grouped by purpose.
-- **Looking for a specific agent?** → [Agents Index](./docs/agents/README.md). 21 agents grouped by role.
-- **Wondering how the agent swarms scale?** → [Sizing](./docs/sizing.md). The small / medium / large dispatch model used by `/architectural-analysis`, `/code-review`, `/gap-analysis`, `/iterative-plan-review`, `/plan-a-feature`, and `/plan-implementation`.
+- **Looking for a specific skill?** → [Skills Index](./docs/skills/README.md). 19 skills grouped by purpose.
+- **Looking for a specific agent?** → [Agents Index](./docs/agents/README.md). 22 agents grouped by role.
+- **Wondering how the agent swarms scale?** → [Sizing](./docs/sizing.md). The small / medium / large dispatch model used by `/architectural-analysis`, `/code-review`, `/gap-analysis`, `/iterative-plan-review`, `/plan-a-feature`, `/plan-implementation`, and `/research`.
 - **Wondering why a skill said "YAGNI"?** → [YAGNI](./docs/yagni.md). The evidence-based rule every planning, review, and architecture skill applies before committing items to an artifact.
 - **Writing or editing a skill or agent?** → [Contributing](./CONTRIBUTING.md).
 
@@ -34,8 +34,8 @@ Add the Test Double skills marketplace to Claude Code, then install the plugin:
 
 - [Concepts](./docs/concepts.md). Skill vs. agent, and how they compose. Read once before using the plugin.
 - [Quickstart](./docs/quickstart.md). Four paths for four common situations. Each path is a short sequence of skills.
-- [Skills Index](./docs/skills/README.md). All 18 skills, grouped by purpose.
-- [Agents Index](./docs/agents/README.md). All 21 agents, grouped by role.
+- [Skills Index](./docs/skills/README.md). All 19 skills, grouped by purpose.
+- [Agents Index](./docs/agents/README.md). All 22 agents, grouped by role.
 - [Sizing](./docs/sizing.md). The small / medium / large model that decides how many agents the swarming skills dispatch.
 - [YAGNI](./docs/yagni.md). The evidence-based "You Aren't Gonna Need It" rule every planning, review, and architecture skill applies.
 - [Contributing](./CONTRIBUTING.md). Adding or editing skills, agents, and documentation.

docs/agents/README.md

@@ -28,9 +28,10 @@ Specialist reviewers whose default posture is adversarial toward the artifact un
 
 ## Investigation & evidence
 
-Agents that gather concrete evidence about a codebase.
+Agents that gather concrete, sourced evidence — from the codebase or the open web.
 
 - **[`evidence-based-investigator`](./evidence-based-investigator.md).** Gathers file paths, line numbers, code snippets, error messages, git history, and test coverage. Dispatched by `/investigate`.
+- **[`research-analyst`](./research-analyst.md).** Researches open-ended questions — options, prior art, trade-offs, how something works — from the open web and provided material, returning sourced evidence and a recommendation. Treats fetched content as claims, never instructions. Dispatched by `/research`.
 - **[`codebase-explorer`](./codebase-explorer.md).** Discovers implementation details for a specific feature: entry points, core logic, data models, configuration, tests.
 - **[`project-scanner`](./project-scanner.md).** Scans repository attributes (languages, frameworks, tooling, configuration). Optimized for config and structure, not deep code tracing. Dispatched by `/project-discovery`.
 

docs/agents/adversarial-security-analyst.md

@@ -106,7 +106,7 @@ URL: https://cwe.mitre.org/
 ## Related documentation
 
 - [Plugin landing page](../../README.md). The front door.
-- [Agents Index](./README.md). All 21 agents, grouped by role.
+- [Agents Index](./README.md). All 22 agents, grouped by role.
 - [`/code-review`](../skills/code-review.md). The skill that always dispatches this agent for security coverage.
 - [`/test-planning`](../skills/test-planning.md). Dispatches this agent for negative security test planning when the files touch auth, input handling, isolation, crypto, uploads, or SQL/ORM.
 - [`devops-engineer`](./devops-engineer.md). Pair on regulated changes. Security analyst covers exploit paths. `devops-engineer` covers operational posture.

docs/agents/adversarial-validator.md

@@ -13,7 +13,7 @@ Operator documentation for the `adversarial-validator` agent in the han plugin.
 ## Key concepts
 
 - **Default posture: everything is wrong until proven right.** The agent assumes the investigation reached the wrong conclusion and the fix will fail. The work is to *try to disprove* the analysis, not confirm it.
-- **Three required strategies.** Challenge the evidence, challenge the fix, challenge the assumptions. The agent must attempt all three. Skipping a strategy makes the validation incomplete.
+- **Four strategies, three always required.** Challenge the evidence, challenge the fix, challenge the assumptions — the agent must attempt all three. A fourth, challenge the evidence-gathering integrity, applies whenever the inputs include gathered evidence, external sources, or research artifacts (always for an investigation evidence summary or a research run): was any item planted, injected, astroturfed, stale, or single-sourced. Skipping an applicable strategy makes the validation incomplete.
 - **Counter-evidence has the same rigor as evidence.** A refutation requires the same `file_path:line_number` plus snippet plus reasoning that the original investigation required. *"Looks wrong"* is not a refutation.
 - **Stale-evidence check is mandatory.** The agent verifies that cited files and line numbers still match the codebase. Evidence from an old branch is not evidence.
 - **Confidence assessment is not optional.** Every run closes with a High / Medium / Low confidence level and a rationale grounded in what the validation found.
@@ -53,7 +53,7 @@ Example prompts:
 
 ## What you get back
 
-- A minimum of 5 numbered `V#` validation items spread across the three strategies (Challenge the Evidence, Challenge the Fix, Challenge the Assumptions). Each item names the strategy, the hypothesis under test, what was investigated (files read, commands run, greps performed), the result (Confirmed / Refuted / Partially Refuted), and the impact.
+- A minimum of 5 numbered `V#` validation items spread across the applicable strategies (Challenge the Evidence, Challenge the Fix, Challenge the Assumptions, and — when the inputs include gathered or external evidence — Challenge the Evidence-Gathering Integrity). Each item names the strategy, the hypothesis under test, what was investigated (files read, commands run, greps performed), the result (Confirmed / Refuted / Partially Refuted), and the impact.
 - A **Confidence Assessment** (High / Medium / Low) with a rationale that points at the validation items behind the call.
 - A **Remaining Risks** section listing known unknowns, areas not fully validated, and assumptions the agent could not verify.
 
@@ -96,7 +96,7 @@ URL: https://en.wikipedia.org/wiki/Red_team
 ## Related documentation
 
 - [Plugin landing page](../../README.md). The front door.
-- [Agents Index](./README.md). All 21 agents, grouped by role.
+- [Agents Index](./README.md). All 22 agents, grouped by role.
 - [`evidence-based-investigator`](./evidence-based-investigator.md). The sibling agent the validator usually attacks. Investigators gather, validators falsify.
 - [`/investigate`](../skills/investigate.md). Always dispatches this agent after the fix plan is drafted.
 - [`/gap-analysis`](../skills/gap-analysis.md). Required swarm role at every size. The swarm runs by default.

docs/agents/behavioral-analyst.md

@@ -87,7 +87,7 @@ URL: https://martinfowler.com/bliki/TwoHardThings.html
 ## Related documentation
 
 - [Plugin landing page](../../README.md). The front door.
-- [Agents Index](./README.md). All 21 agents, grouped by role.
+- [Agents Index](./README.md). All 22 agents, grouped by role.
 - [`structural-analyst`](./structural-analyst.md). Sibling analyst for static structure.
 - [`concurrency-analyst`](./concurrency-analyst.md). Sibling analyst for concurrency hazards.
 - [`risk-analyst`](./risk-analyst.md). Consumes this agent's findings.

docs/agents/codebase-explorer.md

@@ -84,7 +84,7 @@ URL: https://pragprog.com/titles/atevol/software-design-x-rays/
 ## Related documentation
 
 - [Plugin landing page](../../README.md). The front door.
-- [Agents Index](./README.md). All 21 agents, grouped by role.
+- [Agents Index](./README.md). All 22 agents, grouped by role.
 - [`evidence-based-investigator`](./evidence-based-investigator.md). Sibling for bug-focused investigation.
 - [`project-scanner`](./project-scanner.md). Sibling for stack and tooling detection.
 - [`/project-documentation`](../skills/project-documentation.md). Always dispatches this agent.

docs/agents/concurrency-analyst.md

@@ -90,7 +90,7 @@ URL: https://go.dev/talks/2012/waza.slide
 ## Related documentation
 
 - [Plugin landing page](../../README.md). The front door.
-- [Agents Index](./README.md). All 21 agents, grouped by role.
+- [Agents Index](./README.md). All 22 agents, grouped by role.
 - [`structural-analyst`](./structural-analyst.md). Sibling analyst for static structure.
 - [`behavioral-analyst`](./behavioral-analyst.md). Sibling analyst for runtime behavior.
 - [`risk-analyst`](./risk-analyst.md). Consumes this agent's findings.

docs/agents/content-auditor.md

@@ -82,7 +82,7 @@ URL: https://standards.ieee.org/ieee/1063/2554/
 ## Related documentation
 
 - [Plugin landing page](../../README.md). The front door.
-- [Agents Index](./README.md). All 21 agents, grouped by role.
+- [Agents Index](./README.md). All 22 agents, grouped by role.
 - [`gap-analyzer`](./gap-analyzer.md). Sibling agent for comparing two distinct artifacts (spec vs. implementation).
 - [`information-architect`](./information-architect.md). Sibling agent for IA structure of the new doc.
 - [`/project-documentation`](../skills/project-documentation.md). Always dispatches this agent in update mode.

docs/agents/data-engineer.md

@@ -213,7 +213,7 @@ URL: https://cheatsheetseries.owasp.org/cheatsheets/SQL_Injection_Prevention_Che
 
 - [Plugin landing page](../../README.md). The front door. Start here if you arrived from outside the docs tree.
 - [YAGNI](../yagni.md). The evidence-based "You Aren't Gonna Need It" rule this agent applies. The two gates, the acceptable-evidence list, the named anti-patterns, and the deferral format.
-- [Agents Index](./README.md). All 21 agents, grouped by role.
+- [Agents Index](./README.md). All 22 agents, grouped by role.
 - [`devops-engineer`](./devops-engineer.md). Pair on production migrations. This agent covers the schema-level expand-and-contract; `devops-engineer` covers the rollout-level progressive delivery.
 - [`adversarial-security-analyst`](./adversarial-security-analyst.md). Pair on regulated data changes. This agent covers data-level governance; the security analyst covers exploit paths.
 - [agent-domain-focus.md](../guidance/agent-building-guidelines/agent-domain-focus.md). Why the agent uses precise domain vocabulary and named anti-patterns.

docs/agents/devops-engineer.md

@@ -190,7 +190,7 @@ URL: https://martinfowler.com/bliki/StranglerFigApplication.html
 
 - [Plugin landing page](../../README.md). The front door. Start here if you arrived from outside the docs tree.
 - [YAGNI](../yagni.md). The evidence-based "You Aren't Gonna Need It" rule this agent applies. The two gates, the acceptable-evidence list, the named anti-patterns, and the deferral format.
-- [Agents Index](./README.md). All 21 agents, grouped by role.
+- [Agents Index](./README.md). All 22 agents, grouped by role.
 - [`data-engineer`](./data-engineer.md). Pair on production migrations. This agent covers rollout-level progressive delivery; `data-engineer` covers schema-level expand-and-contract.
 - [`adversarial-security-analyst`](./adversarial-security-analyst.md). Pair on changes touching auth, secrets, or regulated surfaces. This agent covers operational readiness; the security analyst covers exploit paths.
 - [agent-domain-focus.md](../guidance/agent-building-guidelines/agent-domain-focus.md). Why the agent uses precise domain vocabulary and named anti-patterns.