/ase-task-research

name: ase-task-research
argument-hint: "[--help|-h] [--services|-s=(all|perplexity|brave|exa|websearch)...] [--refine|-r] [--dry-run|-d] [<id> | <id>: [<topic>] | <topic>]"
description: >
    Research a topic in depth for the current or given task plan, by
    combining Internet/Web search with a grounding in the source
    artifacts of the project, and append the resulting research report
    to the "research" attachment of the task, optionally refining the
    plan by its recommendations. Use when the user wants to "research",
    "investigate", or "look into" a topic for a "task" or "plan".
user-invocable: true
disable-model-invocation: false
effort: high

@${CLAUDE_SKILL_DIR}/../../meta/ase-control.md @${CLAUDE_SKILL_DIR}/../../meta/ase-skill.md @${CLAUDE_SKILL_DIR}/../../meta/ase-getopt.md

<purpose name="ase-task-research"> Research a Topic for a Task Plan </purpose>

<expand name="getopt" arg1="ase-task-research" arg2="--services|-s=(all|perplexity|brave|exa|websearch)... --refine|-r --dry-run|-d --int-source-dir="> $ARGUMENTS </expand>

<objective> *Research* a topic in depth for a task plan, grounded in both the *Internet*/*Web* and the *source artifacts* of the project. </objective>

@${CLAUDE_SKILL_DIR}/../../meta/ase-format-task.md @${CLAUDE_SKILL_DIR}/../../meta/ase-format-meta.md

Procedure ---------

<define name="search-agent">

    Agent(
        description:       "Query Web Search Service: <arg1/>",
        subagent_type:     "ase:ase-meta-search",
        prompt:            <content/>,
        run_in_background: false
    )

</define>

1. **Determine Task and Topic:**

1. Set <topic><getopt-arguments/></topic> initially, with any leading and trailing whitespace stripped. Inherit the always existing <ase-task-id/>, <ase-session-id/>, and <ase-project-boxing/> from the current context. Do not output anything.

2. React on task and/or topic:

• If <topic/> matches the regexp `^[a-zA-Z0-9#][a-zA-Z0-9#_-]*$`,

or has the format `<id/>:` or `<id/>: <text/>` where <id/> matches this regexp: set <ase-task-id><id/></ase-task-id> (or to <topic/> itself for the first form) and <topic/> to <text/> (or to empty for the first two forms), call the `ase_task_id(id: "<ase-task-id/>", session: "<ase-session-id/>")` tool of the `ase` MCP server to switch the task, and then only output the following <template/>:

<template> ⧉ **ASE**: ◉ task: **<ase-task-id/>**, ▶ status: **task given** </template>

• Otherwise, only output the following <template/>:

<template> ⧉ **ASE**: ◉ task: **<ase-task-id/>**, ▶ status: **task inherited** </template>

3. Treat <getopt-option-services/> as a comma-separated list of *backend tokens*. The getopt parser validates only the *first* token, so you *MUST* validate each remaining token yourself against the allowed set `all`, `perplexity`, `brave`, `exa`, `websearch`. If any token is *not* in this set, bind <token/> to that offending token, then only output the following <template/> and then immediately *STOP* processing the entire current skill:

<template> ⧉ **ASE**: ☻ skill: **ase-task-research**, ▶ ERROR: invalid `--services` token: **<token/>** </template>

A backend is *selected* if `all` is in <getopt-option-services/> *OR* that backend's own name is in <getopt-option-services/>.

4. *Load*: call the `ase_task_load(id: "<ase-task-id/>", tag: true)` tool of the `ase` MCP server -- with the `variant` argument defaulting to `source` and the `attachments` argument defaulting to `elided` -- and set <plan/> to its `text` output field without the trailing `<task-plan-tag>` delimiter line, and <tag/> to the content of that line. If <plan/> is empty or starts with `ERROR:` or `WARNING:`, only output the following <template/> and then immediately *STOP* processing the entire current skill:

<template> ⧉ **ASE**: ◉ task: **<ase-task-id/>**, ▶ ERROR: no task plan to research for </template>

5. <if condition="<topic/> is empty"> Research the *task plan itself*: set <topic/> to a concise, self-contained summary of the `# TASK:` title and the `DOM` bullet-points of <plan/> (skipping every bullet-point in the *inert* checkbox states `[-]` and `[>]`). </if> Then only output the following <template/>:

<template> ⧉ **ASE**: ◉ task: **<ase-task-id/>**, ⌕ topic: **<topic/>**, ▶ status: **topic given** </template>

2. **Research the Web:**

1. Derive *two to four* focused, complementary search *queries* <queries/> from <topic/> -- like its established practices and standards, its typical solutions, libraries, or patterns, and its known pitfalls. Each query is a *self-contained* summary of an aspect of <topic/> and *MUST* *NEVER* carry confidential project internals: no file paths, no symbols or identifiers, and no other names taken from the project or from <plan/>, as the queries leave the project towards foreign search services. Do not output anything.

2. Invoke the following tool once per query <query/> of <queries/> and per *selected* backend, emitting *all* invocations *in one single message* so they run in *parallel*:

If the `perplexity` backend is *selected* and the MCP tool `perplexity_search` from the MCP server `search-perplexity` is available:

<expand name="search-agent" arg1="perplexity"> Call the MCP tool `perplexity_search(query: "<query/>")` from the MCP server `search-perplexity`. </expand>

If the