research · diff
v1.1 to git:20260930.482cd8b
9 added, 40 removed. Audit A to A.
---
name: research
- description: "Investigate a question against high-trust primary sources (official docs, codebases, APIs, specs) and produce structured Markdown findings with clear citations. Authored by Matt Pocock, enhanced for cross-environment research."
+ description: Investigate a question against high-trust primary sources and capture the findings as a Markdown file in the repo. Use when the user wants a topic researched, docs or API facts gathered, or reading legwork delegated to a background agent.
author: Matt Pocock (https://github.com/mattpocock/skills)
- contributors: Andrew G. Brown (https://github.com/brownag)
license: MIT
- version: 1.1
+ source: mattpocock-skills
+ source_ref: v1.2.0
+ upstream: https://github.com/mattpocock/skills
---
-
- # Research
-
- Investigate questions against high-trust primary sources and capture findings in clean, well-structured Markdown documents with explicit source citations.
-
- ## When to Use
-
- - Researching a framework, API, tool, or library before implementing.
- - Investigating codebase architecture, existing patterns, or tool surfaces.
- - Delegating reading and exploration legwork to a background or specialized agent.
- - Gathering primary facts from official documentation, RFCs/specs, or source repositories.
-
- ## Workflow
-
- 1. **Clarify the Research Scope & Question**
- - Pin down the core questions, target libraries/APIs, or specific subsystems.
- - Determine whether research targets local codebases, remote Git repositories, or online official documentation.
-
- 2. **Delegate or Run in Focused Context**
- - When running in an interactive CLI session with sub-agent capabilities, spin up a background agent (`agent_type: research` or `explore`) to gather findings without blocking parent turns.
- - When running in single-turn or resource-constrained environments, use targeted file inspection, MCP server queries, or web tools directly.
-
- 3. **Query Primary Sources First**
- - Prioritize authoritative first-party sources:
- - Official project documentation, API references, and RFC/W3C/IETF specs.
- - Direct source code, test suites, and configuration files.
- - Upstream GitHub releases, changelogs, and package manifests.
- - Avoid relying on secondary blog posts, forums, or unchecked summaries unless primary sources are unavailable.
+ Spin up a **background agent** to do the research, so you keep working while it reads.
- 4. **Structure the Findings**
- - Create a clean Markdown artifact containing:
- - **Summary / Key Findings**: High-level answers to the research question.
- - **Detailed Analysis / Architecture**: In-depth examination, code snippets, or diagrams (Mermaid where appropriate).
- - **Source Citations**: Explicit links, file paths, and commit/version references for every significant claim.
- - **Implementation Implications / Next Steps**: Concrete takeaways for planning or execution.
+ Its job:
- 5. **Save to Repository Convention**
- - Save the compiled report under the repository's established research directory (e.g., `planning/`, `docs/research/`, or a session-specific folder).
- - Inform the user of the output path and highlight critical takeaways.
+ 1. Investigate the question against **primary sources** — official docs, source code, specs, first-party APIs — not a secondary write-up of them. Follow every claim back to the source that owns it.
+ 2. Write the findings to a single Markdown file, citing each claim's source.
+ 3. Save it where the repo already keeps such notes; match the existing convention, and if there is none, put it somewhere sensible and say where.