agentleFS
ali-demirbasali-demirbas/research/skills/research-planner/SKILL.md

research-planner

Skill0 starsChanged 3 months agoMITView on GitHub

Use when a research question needs to be broken into sub-questions, matched to which source skills apply, and given a search budget and stopping condition — before any source skill starts collecting. Triggers on "plan this research", "break this question down", or is invoked automatically by the research-intelligence orchestrator as its first stage. Do NOT use this to collect evidence yourself (dispatch the source skills for that) or to judge evidence quality (that's source-verify and the validator).

3 other projects use a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

1 rule. About 0 are common, 1 is distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    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:

    If the user doesn't respond with changes, proceed with the drafted plan — this is a confirmation checkpoint, not a blocking questionnaire.

    line 39

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “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 Planner

Overview

Turns one research question into a run plan: sub-questions, which source skills to dispatch for each, a search budget, and the condition that ends the run. This skill produces a plan, not evidence — its output is consumed by the orchestrator, which then dispatches the actual source skills.

Workflow

  1. Decompose the question into sub-questions. Non-overlapping, each answerable somewhat independently. Budget the count to the question's actual complexity — don't manufacture 5 sub-questions for something that's really 1-2, and don't force a genuinely broad question into 1.
    • Simple fact-finding: 1-2 sub-questions.
    • Comparative ("X vs Y"): one sub-question per compared element, capped around 3.
    • Complex/open investigation: 3-5 sub-questions.
  2. Match each sub-question to source skills. A sub-question can dispatch more than one source skill — pick by what kind of evidence would actually settle it, not by habit:
    • A claim about official specs/pricing/terms → official-source-research (+ web-research to find it if the URL isn't already known).
    • A claim about whether something actually works/ships → github-research (+ web-research for docs).
    • A claim about user sentiment/demand/pain points → reddit-research + social-research.
    • A claim about a launch/event → news-research (which itself traces to official-source-research when it finds a press-release root).
    • A claim resting on published research → academic-research.
    • A practitioner's direct account → blog-research.
  3. Set a search budget per sub-question, scaled to the same complexity tiers as decomposition — a simple sub-question gets 3-5 searches, a complex one more, but state the number explicitly in the plan so source skills know when they've done enough for this round.
  4. One sub-question, one claim_class. If a question mixes kinds — "do people like X, and does it actually work?" — split it: one community-signal sub-question and one implementation sub-question. A single sub-question carrying both forces one bar onto evidence that should face two, which is how community volume ends up grading a technical claim. Declare each sub-question's claim_class (fact / implementation / community-signal / opinion). This is not bookkeeping: it determines which quality bar the eventual finding must clear (engine/ranking.md), and therefore what "enough evidence" means for this sub-question before any search runs. Declaring it up front is also what stops the class from being back-inferred from whatever evidence happened to turn up.
  5. Set the stopping condition (constitution rule 11). Two distinct rules, deliberately separated:
    • Global stop: the run ends after 2 consecutive rounds in which no new evidence was collected across all still-active sub-questions. "New evidence" is defined in engine/dedup.md — a restatement of an existing claim from an existing root is not new.
    • Per-sub-question saturation: a sub-question that meets its claim-class bar, or that individually returns nothing new for 2 rounds, stops drawing budget. It does not end the run; other sub-questions keep going. A sub-question still open when the run stops is a gap, not a failure; it goes to the report's gaps section.
  6. Confirm scope with the user before dispatch — required for anything beyond quick-research. Steps 1-5 are cheap: no network calls, just a draft plan. Before turning that draft into real dispatch, show it and ask what to narrow:

    This will check N sub-questions across these sources: <list>. Want me to focus on specific ones, skip any, or run the full set?

    This exists because a deep-research/market-research/competitive-research/technology-research run can touch most of the 8 source skills and take a long time — asking before collection starts is the only point where narrowing is cheap. A user who says "just check GitHub and the docs" turns a 6-source draft into a 2-source dispatch before a single search runs.

    Skip this gate for quick-research — that workflow is already narrow by design (1-2 sub-questions, 2-3 sources, 1 round; see workflows/quick-research.md), and for any request where the user already named the specific source(s) they want ("search GitHub for X" routes straight to github-research, bypassing the planner entirely — this gate only applies when the full pipeline is what's running).

    If the user doesn't respond with changes, proceed with the drafted plan — this is a confirmation checkpoint, not a blocking questionnaire; don't re-ask for depth beyond one round of narrowing.

  7. Write the confirmed plan to the run's ledger (state/ledger.md format) before dispatch: sub-questions, claim classes, assigned source skills, budget, stopping condition, and any narrowing the user requested at step 6. This is the artifact the orchestrator hands to source skills and later checks the run against — plan before work, not vibes.

Output

A written, user-confirmed plan (sub-questions → claim class → source skills → budget → stopping condition), not evidence records. The orchestrator dispatches source skills against this plan.

Common mistakes

MistakeFix
Manufacturing sub-questions to look thoroughMatch count to actual question complexity
Dispatching every source skill to every sub-questionMatch source skill to what kind of evidence would settle that specific sub-question
Leaving claim_class for the synthesizer to figure out laterDeclare it now — it defines the bar, and back-inferring it from collected evidence is how a fact claim ends up graded on community volume
No stated budget, letting each source skill decide for itselfState the number in the plan — it's what makes "enough for this round" checkable
Ending the whole run because one sub-question went quietPer-sub-question saturation stops that sub-question's budget only; the global stop needs all active sub-questions dry for 2 rounds
Treating an open sub-question at stop-time as a failureIt's a gap; log it, don't force premature evidence to close it
Dispatching a broad multi-source plan straight to collection without showing it firstConfirm scope with the user (step 6) for anything beyond quick-research — this is the cheap point to narrow, before any search runs
Asking the scope question on a quick-research or single-named-source requestThose are already narrow by design; the gate only applies to the full multi-source pipeline

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.