holocron/plugins/bin/.apm/skills/research/SKILL.md

name, description, metadata, allowed-tools, model

name	description	metadata	allowed-tools	model
research	Use when the user wants to research a topic and generate structured reference markdown files. Handles: finding canonical docs for a tool/library/API via Context7 MCP or web sources, reading and deepening into linked pages, organizing extracted content into topic files (overview, installation, configuration, cli-reference, api-reference, examples, troubleshooting). Do NOT use when the user wants to write documentation from existing code or specs (use write-docs), install or manage the neuledge-context MCP server (use neuledge-context), or research a bug/incident (use diagnose).	category research	WebSearch WebFetch Read Write mcp__context7__resolve-library-id mcp__context7__query-docs	sonnet

Required inputs

• Topic — the subject to research (tool, library, API, concept); inferred from user description if clear, ask if ambiguous
• Output path — directory where reference files will be written; must be provided explicitly — do not infer or default
• Starting URLs — optional; if provided, skip discovery websearch and read these first

Constraints

• Never write files outside the explicitly provided output path
• Skip any default topic file if no relevant content is found for it — do not create empty files
• Create additional topic files beyond the default list when content warrants it (e.g. webhooks.md, rate-limits.md)
• Subagents handle parallel source reading and link deepening — the orchestrator writes all files; subagents return summaries only, never write directly
• Context7 MCP calls (resolve-library-id, query-docs) are made only by the orchestrator at step 2 — subagents must not call them
• sources.md is always written, even if only one source was read
• Each topic file must have frontmatter with topic and source_keys; body is prose only — no inline URLs
• Source keys in sources.md must be kebab-case slugs: derived from the source domain or page title for web sources; for Context7 sources use context7-<library-slug> (e.g. context7-vercel-next-js)
• Default topic list and file format spec live in references/ sub-files — read them at step 1

Process

1. Scan codebase. Search the working directory for existing usage of the topic — imports, config files, version pins, existing reference files. Use findings to narrow research scope (e.g. target the version already in use, skip topics already documented). Read references/topics.md for the default topic list and references/file-format.md for the output file format spec.

2. Try Context7. If the topic is a library, framework, or API and no starting URLs were provided, call resolve-library-id with the topic name and the user's question. If a match resolves, call query-docs once per default topic area (see references/topics.md). Treat each response as a source summary with slug context7-<library-slug> (e.g. context7-vercel-next-js). A topic area has sufficient content when the Context7 response contains at least one substantive paragraph — not a "no results" message, redirect notice, or header-only boilerplate. Mark covered topic areas — skip their subagent web reads in step 4. If the library does not resolve, or starting URLs were provided (explicit source choice by the user), skip this step entirely.

3. Discover sources. For topics not covered by Context7 (or when no starting URLs were provided and Context7 did not resolve), websearch for canonical documentation (prefer llms.txt, developer docs, official API references over tutorials or blog posts). Collect 3–5 candidate URLs before reading any.

4. Read sources in parallel. Spawn one subagent per source URL. Each subagent fetches the page, extracts relevant content, identifies links worth deepening, and returns a structured summary (content by topic area + links to follow). Subagents do not write files.

5. Deepen. For each subagent that returned links worth following, spawn child subagents per branch. Continue until content becomes repetitive or out of scope. Cap at ~10 additional pages total across all branches.

6. Consolidate. Merge all subagent summaries (Context7 and web) by topic area. Identify which default topics have sufficient content and which custom topics emerged.

7. Write topic files. For each topic with content, write <output-path>/<topic>.md using the format in references/file-format.md. Orchestrator writes all files — never delegate file writing to a subagent.

8. Write sources.md. Write <output-path>/sources.md mapping each source slug to its URL (use context7:<library-id> as the URL for Context7 sources), description, and list of topic files it contributed to. Include sources that yielded no content, marked no content extracted.

Output format

• <output-path>/<topic>.md per topic with content — formatted per references/file-format.md
• <output-path>/sources.md — always produced; maps slug → URL, description, contributing files

Failure handling

• Output path not provided — stop and ask; do not infer or default
• No sources found after websearch — report what was searched, ask user to provide starting URLs
• Subagent returns no usable content — skip that source, log in sources.md as no content extracted
• All topic files would be empty — stop, report what was searched, do not write any files

Self-check

• Codebase scanned before any websearch was performed
• Output path was explicitly provided — not inferred
• references/topics.md and references/file-format.md read at step 1
• Context7 resolution attempted before websearch when topic is a library/framework/API
• Context7 calls made only at orchestrator step 2 — no subagent called resolve-library-id or query-docs
• Context7 sources recorded in sources.md with context7:<library-id> as URL
• No topic file written without content
• sources.md written with all sources read (including those with no content extracted)
• All file writes performed by the orchestrator, not subagents
• Each topic file has topic and source_keys frontmatter fields
• All source keys in topic files have a matching entry in sources.md
• No files written outside the provided output path