with one click
evidence-research
// Gathers internal or external evidence for one decision and returns sourced patterns. Use when design, planning, retrospectives, or architecture depends on research before deciding.
// Gathers internal or external evidence for one decision and returns sourced patterns. Use when design, planning, retrospectives, or architecture depends on research before deciding.
Creates or revises one portable agent skill with concise routing, progressive disclosure, and clear safety boundaries. Use when the user wants to write, clean up, or restructure a skill.
Finds Codex session coordinates by id, title, repo path, rollout path, or topic. Use when a user or another skill needs thread metadata and rollout paths for its own review.
Reviews recent Codex sessions for repeated agent failures and skill improvements. Use for daily/weekly retrospectives, skill audits, agent-pattern analysis, or cleanup recommendations.
Clarifies fuzzy direction into durable memory and issue-shaping handoff. Use when the user wants to turn an idea, conversation, ADR, PRD, or prior session into clear agent-ready work.
Skips obvious branches inside grilling sessions by stating the assumed answer and moving on. Use when the user says fast-forward, skip, obvious, same as me, or next unclear area.
Grilling session that challenges your plan against the existing domain model, sharpens terminology, and updates agent-owned documentation under `.agents/` inline as decisions crystallise. Use when the real task is defining purpose, scope, structure, canonical terms, capture/refinement criteria, or other durable decisions for the project.
| name | evidence-research |
| description | Gathers internal or external evidence for one decision and returns sourced patterns. Use when design, planning, retrospectives, or architecture depends on research before deciding. |
Use this when a design or grilling decision depends on evidence that should be gathered and synthesized before acting.
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.
ecosystem, internal, or mixed.targeted, standard, or ambitious.synthesis.md when findings are substantive.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.
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.
Use this layout:
<os-temp-dir>/evidence-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 /Users/maxi/vitehub/vitehub/.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.
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.
Write synthesis.md when reports contain substantive evidence. Keep it concise and decision-oriented:
SUPPORTED, CONTESTED, WEAK, or INCONCLUSIVEIf 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.
Return a compact answer:
Research artifacts:
- Brief: <os-temp-dir>/evidence-research/<project>/<topic>/brief.md
- Synthesis: <os-temp-dir>/evidence-research/<project>/<topic>/synthesis.md
Findings:
- ...
Decision pressure:
- ...
Next grilling question:
...