agentleFS
jacartyjacarty/claude-toolkit/.claude/skills/research-brief/SKILL.md

research-brief

Skill0 starsChanged 6 months agoMITView on GitHub

Investigate a problem, feature, or project idea and produce a structured research brief with findings, recommended approach, and open questions. Use when the user wants to understand the technical landscape before building — comparing libraries, frameworks, patterns, or approaches. Triggers include "research this", "investigate", "what are the options for", "how should I approach", "what tools exist for", "compare approaches to", "do a deep dive on", "technical research for", or any situation where the user needs to gather information and form a recommendation before committing to an implementation path. Also use when a requirements document or tracked issue exists and needs technical investigation before a spec can be written.

20 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use weekly-review.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • QuixiAISkill

    weekly-review

    Review the past week across goals, tasks, calendar, journal, and commitments, then propose the next week

    Also in 3 projects that use this

The file

Show its rules and text

We split this skill into the rules it gives an agent

15 rules. 0 are common, 15 are distinctive, and 0 are very specific to this project.

  • 0

    Common

    Most of the 19 edited versions we read keep these.

  • 15

    Distinctive

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Do NOT use when:

    line 38
  2. Distinctive:

    Look for pitfalls others have encountered.

    line 70
  3. Distinctive:

    Use your tools — don't guess when you can look things up:

    line 79
  4. Distinctive:

    Run multiple searches with different queries.

    line 82
  5. Distinctive:

    Use whatever tools are available in the current environment.

    line 88
  6. Distinctive:

    If the research surfaces a decision between competing approaches, note it.

    line 97
  7. Distinctive:

    If no additional tools are connected, skip this step.

    line 108
  8. Distinctive:

    When posting to an issue tracker, check for existing research briefs before posting to avoid duplicates.

    line 110
  9. Distinctive:

    After a research brief is produced, the natural next steps are:

    line 153
  10. Distinctive:

    Prefer concrete over abstract.

    line 165
  11. Distinctive:

    When comparing options, state trade-offs clearly.

    line 166
  12. Distinctive:

    If the problem is well-understood and straightforward, say so.

    line 167
  13. Distinctive:

    If the problem is underspecified or has significant risks, call that out clearly.

    line 169
  14. Distinctive:

    Don't hallucinate capabilities or libraries.

    line 170
  15. Distinctive:

    Don't soften them, but acknowledge the user's starting position and explain why the evidence points elsewhere.

    line 182

“Common” is measured: kept by at least 6 in 10 of the 19 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Research Brief — Technical Investigation & Recommendation

What This Skill Does

This skill investigates a problem space and produces a structured research brief — a document that summarises findings, compares options, makes a concrete recommendation, and identifies open questions. The brief is designed to be consumed by a developer (or by the implementation-spec skill) as the basis for technical decisions.

It is not a literature review. The output should be actionable: "here's what I found, here's what I recommend, here's what's still uncertain."

When to Use This Skill

Use when:

  • The user has a problem or feature and needs to understand the solution landscape
  • A requirements document exists and the next step is technical investigation
  • A tracked issue needs research before implementation can begin
  • The user says "how should I approach this?" or "what are the options?"
  • Multiple libraries, frameworks, or patterns could solve the problem and the user needs a comparison

Do NOT use when:

  • The user already knows what to build and wants a spec (use implementation-spec)
  • The decision is between 2-3 known options (use trade-off-analysis — it's faster)
  • The user wants to brainstorm approaches (use tree-of-thought or graph-of-thought)
  • The problem is well-understood and just needs implementing (just do it)

Process

Step 1 — Understand What Needs Researching

Identify the research scope from one of these sources:

  • A tracked issue — if the user points to an issue in a project tracker, read it using whatever tools are available. Extract what is being asked for, constraints, and any parent issue or project context.
  • A requirements document — if requirements were produced by the requirements-elicitation skill, read them and identify the areas that need technical investigation.
  • A verbal brief — if the user describes the problem conversationally, extract the core question and confirm scope before researching.

State what you're researching and what questions you're trying to answer. Confirm with the user if the scope is ambiguous.

Step 2 — Research

Adapt your research approach to the type of problem:

  • Technical implementation (building, coding, integrating): Search for libraries, frameworks, best practices, existing implementations. Compare approaches with trade-offs. Look for pitfalls others have encountered.
  • Data and infrastructure (ingestion, storage, pipelines): Search for data formats, parsing tools, storage patterns, scalability considerations. Check for existing solutions before recommending custom builds.
  • Evaluation and methodology (testing, metrics, quality): Search for established frameworks, standard metrics, published methodologies. Look for real-world results.
  • Architecture and design (choosing between approaches, system design): Search for comparison articles, architecture patterns, case studies. Focus on trade-offs.

Use your tools — don't guess when you can look things up:

  • Web search — search for libraries, documentation, comparison articles, known pitfalls. Run multiple searches with different queries. Refine based on what you find.
  • Repository access — if a target repository exists, read relevant files to ground research in the actual codebase. Check for a CLAUDE.md or similar project context file.
  • Issue tracker — read issues and comments for context if the research is tied to a tracked piece of work.

Use whatever tools are available in the current environment. These categories aren't exhaustive or mutually exclusive. Many problems span multiple types. Use judgement.

Step 3 — Synthesise and Recommend

Distil your findings into a structured brief. Every recommendation must be grounded in something you found, not in general knowledge. Be specific: "use pdfplumber 0.11+ with extract_tables" not "consider using a PDF parsing library."

If the research surfaces a decision between competing approaches, note it. The user can run the trade-off-analysis skill on that specific decision if they want a deeper comparison.

Step 4 — Delivery

Produce the full research brief as markdown using the output template below. This is always the primary output.

Then ask the user if they would like the output additionally delivered via any connected tools (e.g. posted as a comment on a tracked issue, saved to a shared document, etc.). Use whatever tools are available in the current environment. If no additional tools are connected, skip this step.

When posting to an issue tracker, check for existing research briefs before posting to avoid duplicates.


Output Template

# Research Brief: [Topic or Issue Title]

**Source:** [Issue reference, requirements doc, or verbal brief summary]
**Date:** [current date]
**Tools used:** [list each tool called during research]

## Summary
One paragraph: what was researched, what the key challenge is, and how it fits into
the broader project context (if applicable).

## Key Findings
Numbered list of the most important discoveries. Each finding should be specific and
actionable — not "there are many libraries available" but "pdfplumber preserves table
structure better than PyMuPDF for regulatory documents, based on comparisons in X and Y."

## Recommended Approach
Concrete recommendation for how to tackle this. Structure as a sequence of steps.
Justify each step by referencing findings. If there are meaningful alternatives, briefly
note them and explain why this approach is recommended over the others.

## Trade-Off Decisions
Any decisions that surfaced during research where multiple viable options exist. For
each, note the options and either make a recommendation or flag it for a dedicated
trade-off analysis.

## Open Questions
Things the research couldn't answer, ambiguities needing human judgement, or risks
to consider before starting implementation.

## Next Steps
Ordered list of concrete actions to take after reading this brief.

What Comes Next

After a research brief is produced, the natural next steps are:

  • Trade-off analysis (trade-off-analysis skill) — if the research surfaced a decision between 2-3 competing approaches, run a structured comparison.
  • Implementation spec (implementation-spec skill) — combine the requirements and research brief into a phased build plan with acceptance criteria.

Interaction Style

  • Thorough but focused. A good brief is 500-1500 words, not 3000.
  • Prefer concrete over abstract. Name specific tools, versions, and patterns.
  • When comparing options, state trade-offs clearly. Make a recommendation and say why.
  • If the problem is well-understood and straightforward, say so. Don't manufacture complexity.
  • If the problem is underspecified or has significant risks, call that out clearly.
  • Don't hallucinate capabilities or libraries. If you're not sure, search for it.
  • British English spelling and punctuation.

Handling Edge Cases

  • No tracked issue exists: Work from the verbal brief or requirements document.
  • Research turns up nothing useful: Say so. Note what you searched for and why the results were thin. This is valuable information — it tells the user they're in uncharted territory.
  • Scope is too broad: Suggest decomposing into focused research questions. Tackle the most critical one first and note the others for follow-up.
  • Research contradicts the user's assumptions: Present the findings neutrally. Don't soften them, but acknowledge the user's starting position and explain why the evidence points elsewhere.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.