Produce cited technical research with ak:research

Use ak:research to evaluate technical solutions, architectures, operational requirements, and current best practices before implementation. The Skill defines the decision and evidence criteria, gathers a bounded set of current sources, cross-checks material claims, and writes a cited Markdown report.

Choose ak:research for a decision-ready report

Use ak:research when

• You need to compare technologies or architecture approaches against explicit requirements.
• Security, scalability, maintainability, maturity, or compatibility needs current external evidence.
• The answer must separate consensus, disagreement, version differences, and unknowns.
• You need a durable research artifact that can feed brainstorming or planning.

Choose another workflow when

• You need one library's current API documentation. Use ak:docs-seeker.
• You need repository-local facts. Use ak:scout.
• You need to design the research instructions but not execute them. Use ak:research-prompt.
• You already have an approved solution and need implementation. Use ak:cook.

Prepare the decision and output path

Before you start:

• Complete Onboarding, and confirm Engineer Kit is installed for the runtime and scope you use.
• State the decision, alternatives, constraints, non-goals, evaluation criteria, recency window, geography or deployment scope, and acceptable evidence types.
• Provide a Report: path from the active naming contract. If none is available, the source-defined workflow must ask for an output path rather than choose an unreviewed location.
• Identify confidential context that must not become a search query or be sent to an external provider.
• Set a research-call budget at or below five; the Skill has a hard maximum of five research tool calls and must respect a lower user limit.

Run the Skill

/ak:research "Compare Postgres row-level security and service-layer authorization for a multi-tenant B2B API. Use official docs, current security guidance, and primary benchmarks; max 4 research calls; Report: plans/research/tenant-authorization.md."

/ak:research "Compare Postgres row-level security and service-layer authorization for a multi-tenant B2B API. Use official docs, current security guidance, and primary benchmarks; max 4 research calls; Report: plans/research/tenant-authorization.md."

$ak:research "Compare Postgres row-level security and service-layer authorization for a multi-tenant B2B API. Use official docs, current security guidance, and primary benchmarks; max 4 research calls; Report: plans/research/tenant-authorization.md."

The Skill accepts a topic as free-form input. By default, it researches the full requested scope and adds nothing unrequested. Add --yagni to challenge and cut scope that is not needed for the stated outcome. Legacy configuration keys for Gemini are compatibility inputs only and do not activate a separate CLI research provider.

Evidence priority

Every material claim should cite the page that supports it. Search-result snippets, index pages, popularity, and model memory are discovery aids rather than evidence.

Understand what happens during a run

1. The Skill defines scope. It records the decision, terms, recency need, evaluation criteria, depth, boundaries, and report destination.
2. It plans the search budget. Up to five precise research calls cover distinct evidence gaps without duplicating queries.
3. It gathers primary sources. Official documentation, specifications, repositories, changelogs, advisories, and versioned references come first.
4. It analyzes deeply. The Skill checks dates, versions, methodology, authentication requirements, deprecations, security implications, and compatibility.
5. It cross-references claims. Independent evidence is used where it adds confidence; conflicts and inferred conclusions are labeled.
6. It synthesizes the decision. Findings map to the stated criteria, with trade-offs, common pitfalls, implementation implications, and actionable next steps.
7. It writes the report. The source-defined workflow organizes and saves a timestamped, cited Markdown artifact and lists unresolved questions last.

Keep external research safe

• Native web search and page retrieval contact external providers and websites; quotas, rate limits, terms, logging, and cost depend on the active runtime.
• Access to private repositories, paid reports, authenticated APIs, or video transcripts requires separate credentials and approval.
• Do not copy credentials into the report. Record only the source and access limitation needed to interpret the evidence.
• Research does not authorize implementation, package installation, repository cloning, publication, messaging, or deployment. Ask before expanding into any of those effects.
• High-stakes security conclusions need current primary advisories and explicit uncertainty; absence of a reported vulnerability is not proof of safety.

Verify the report

A complete report should contain the research timestamp, scope, methodology, source count and date range, criteria, key findings, comparative analysis, security and performance evidence where relevant, recommendations, citations, actionable next steps, and unresolved questions. Each recommendation should trace to both a decision criterion and supporting evidence.

The Skill bundles no test suite or deterministic research script. Verification therefore means opening the saved report, checking links and dates, matching citations to claims, confirming version and benchmark scope, reviewing the diff, and ensuring the file exists at the approved Report: path.

Troubleshoot or continue

Know the current limits

• Research quality is limited by accessible sources, publication quality, provider indexing, paywalls, language coverage, and the five-call budget.
• “Current” is evaluated at run time; cached or undated material must not be presented as current without verification.
• Recommendations are decision guidance, not proof that an implementation will satisfy production security or performance requirements.
• The workflow produces a report artifact by design; use ak:research-prompt when you want guidance only and no research execution.
• Stable and beta package identical ak:research methodology and output rules.