RESEARCH-RIGOR.md
# Research Rigor
## Source-Area Matrix
Before spawning subagents, write a source-area matrix in `brief.md`. Each row must name:
- source area
- why it is comparable
- priority sources
- report path
- questions this source area must answer
- what would change in the target design if this source area is persuasive
For broad platform or library design questions, consider splitting into official vendor docs, technical blogs, source repositories, comparable libraries, academic or benchmark papers, security or operations writing, and user-facing product documentation. Only include source areas that can change the decision.
## Subagent Reports
Each subagent prompt should include the `brief.md` path, assigned source area, report path, chosen depth, source minimum for that area, whether source cloning into `sources/` is useful, a no-repo-mutation requirement, and a request for source links, trade-offs, patterns, disagreements, recommendations, and evidence-versus-inference separation.
Use at least one subagent. Use multiple subagents when source areas are meaningfully independent, such as framework ecosystems, product ecosystems, company technical writing, benchmarks, security literature, Codex session clusters, PR stacks, and repository history.
Subagents must write the requested report file. A progress message without a report is incomplete.
## Source Guidance
Prefer authoritative and current sources: official docs, source repositories, technical blogs from relevant companies, design notes, RFCs, changelogs, and established comparable libraries or products.
"Others" means comparable systems facing a similar design challenge. Ask the subagent to justify why each comparison is relevant.
Do not stop at vendor docs for ambitious research if source repositories, benchmark papers, security writing, or competing products can change the decision.
Every report must distinguish:
- direct evidence from a source
- interpretation of what the source implies
- applicability limits for the current project
- disagreements between sources
Avoid source padding. If a source is weak or only adjacent, label it as adjacent and explain why it still matters.
## Finding Verdicts
Every major synthesis claim must use this shape:
```md
Claim:
Verdict: SUPPORTED | CONTESTED | WEAK | INCONCLUSIVE
Evidence:
Inference:
Applicability:
Confidence:
What would change in our design:
```
Verdict rules:
- `SUPPORTED`: multiple authoritative sources point in the same direction, and applicability to the project is clear.
- `CONTESTED`: credible sources disagree, or the pattern changes by ecosystem, repository, scale, or product constraints.
- `WEAK`: evidence is adjacent, anecdotal, old, vendor-specific, or not enough to drive a decision alone.
- `INCONCLUSIVE`: sources do not answer the question, or the research method was not strong enough to resolve it.
Separate decision-changing evidence from background context. Background can explain the landscape, but it must not carry the recommendation unless it changes the target design.
## Completion Gate
Before writing `synthesis.md`, verify:
- each expected report path exists
- each report contains source links with relevance notes
- each report answers its assigned questions
- each report has patterns, trade-offs, recommendations, and applicability limits
- broad or high-stakes research has evidence-versus-inference separation
- no report only summarizes one vendor/source family unless it was explicitly assigned that narrow area
- each major synthesis claim has a finding verdict
- decision-changing evidence is separated from background context
If any report fails the gate, send a follow-up prompt to that subagent or run a local repair pass before synthesis. In the final answer, mention any report that remained weak and why.
SKILL.md
---
name: ecosystem-research
description: Researches internal or external ecosystem evidence for a design decision and returns decision-oriented patterns with sources. Use during design, grilling, retrospectives, architecture work, or implementation planning when the user asks to research a topic, compare external systems, inspect prior sessions, analyze patterns, or gather evidence before deciding.
---
# Ecosystem Research
## Quick Start
Use this when a design or grilling decision depends on evidence that should be gathered and synthesized before acting.
## Source Modes
- `ecosystem`: external systems, libraries, products, docs, public precedent, and technical writing.
- `internal`: repository history, Codex sessions, PRs, issues, ADRs, local docs, and project-specific evidence.
- `mixed`: internal evidence plus external precedent.
Default to `ecosystem` when the user asks how others solve a problem, compares products/libraries, or mentions ecosystem precedent. Default to `internal` for retrospectives, session analysis, project history, or repo-local pattern analysis. Use `mixed` when both would change the decision.
## Workflow
1. Form a concrete research question from the active design branch.
2. Choose a source mode: `ecosystem`, `internal`, or `mixed`.
3. Choose a research depth: `targeted`, `standard`, or `ambitious`.
4. Identify the absolute project root and create a persisted research brief.
5. Spawn subagents according to the depth and source-area split.
6. Have subagents write reports under the research folder.
7. Verify every expected report exists and meets the evidence bar before synthesis.
8. Synthesize the reports into a concise `synthesis.md` when findings are substantive.
9. Return decision-oriented findings to the active session and continue with one question.
Do not mutate the project repo. Research artifacts belong under the temporary directory of the user's OS, not the current workspace. Resolve it with the platform temp-dir API or environment, such as `$TMPDIR` on macOS/Linux or `%TEMP%` on Windows. If subagents are unavailable, state that and do a compact local fallback.
## Research Depth
Default to `standard` unless the user asks for "quick", "ambitious", "proper research", "deep research", or the decision is public API, security, data model, migration, pricing, irreversible architecture, or high-conflict.
- `targeted`: one narrow source area, at least one subagent, at least 5 authoritative sources, one report, synthesis optional.
- `standard`: 2-4 distinct source areas, 2-4 subagents when available, at least 12 authoritative sources total, synthesis required.
- `ambitious`: broad or high-stakes work, 4+ source areas, 4+ subagents when available or staged local passes, at least 20 authoritative sources total, synthesis required, explicit evidence-versus-inference table required.
If the user says the first pass was too shallow, immediately upgrade to `ambitious`. Do not repeat the same source area with a slightly longer prompt; add missing source areas and stronger completion checks.
## Artifact Layout
Use this layout:
```text
<os-temp-dir>/ecosystem-research/<project>/<topic>/
+-- brief.md
+-- sources/
+-- reports/
+-- synthesis.md
```
`brief.md` should include the project/context name, absolute `project_root`, active design question, relevant conversation history, user concerns, resolved decisions, unresolved branches, research questions, source mode, chosen depth, source-area matrix, minimum source bar, report paths, and source priorities.
Because research artifacts live outside the project workspace, any project file reference in the brief, reports, synthesis, or subagent prompt must be absolute, such as `<absolute-project-root>/.agents/contexts/devtools/CONTEXT.md`. Never use repo-relative paths like `.agents/...` inside temporary artifacts unless they are paired with the absolute `project_root`.
Subagents should read `brief.md`.
For source-area matrices, report requirements, source-quality rules, and completion checks, use [RESEARCH-RIGOR.md](RESEARCH-RIGOR.md).
## Subagent Brief
Each subagent prompt should include the `brief.md` path, assigned source area, report path, chosen depth, source minimum for that area, whether source cloning into `sources/` is useful, a no-repo-mutation requirement, and a request for source links, trade-offs, patterns, disagreements, recommendations, and evidence-versus-inference separation.
Use at least one subagent. Use multiple subagents when source areas are meaningfully independent, such as framework ecosystems, product ecosystems, company technical writing, benchmarks, security literature, Codex session clusters, PR stacks, or repository history.
Subagents must write the requested report file. A progress message without a report is incomplete.
## Synthesis
Write `synthesis.md` when reports contain substantive evidence. Keep it concise and decision-oriented:
- consensus patterns
- meaningful disagreements
- applicability to this project
- risks and trade-offs
- evidence versus inference
- finding verdicts: `SUPPORTED`, `CONTESTED`, `WEAK`, or `INCONCLUSIVE`
- source-area coverage and gaps
- decision-changing evidence separated from background context
- recommended decision wording
- source links
If an ADR follows, tell the active grilling skill which learnings are worth carrying into the ADR. Do not write project ADRs directly from this skill.
## Output Shape
Return a compact answer:
```md
Research artifacts:
- Brief: <os-temp-dir>/ecosystem-research/<project>/<topic>/brief.md
- Synthesis: <os-temp-dir>/ecosystem-research/<project>/<topic>/synthesis.md
Findings:
- ...
Decision pressure:
- ...
Next grilling question:
...
```