best-practice-research

Files (1)

• SKILL.md

SKILL.md (first lines)

# Best-Practice Research

Use this skill when a task depends on current external best practices,
version-aware guidance, standards, official recommendations, or upstream
behavior. This is a workflow wrapper: it routes evidence gathering and
synthesis; it is not a new research authority and it does not replace the
researcher lane.

## Purpose

Produce a cited, reusable best-practice answer or handoff that separates
current external evidence from repo-local facts and dependency-selection
decisions.

## Activate When

- The user asks for best practices, recommended approach, current guidance,
  official recommendations, standards, or version-aware external behavior.
- `/omagy:ralplan`, `/omagy:deep-interview`, `/omagy:team`, or another Omagy
  workflow needs current external evidence before planning or execution can be
  correct.
- The task involves an already chosen technology and needs authoritative usage
  guidance, migration notes, API behavior, lifecycle rules, or current safety
  guidance.

## Do Not Activate When

- The answer is fully repo-local; use `omagy explore --prompt "<narrow lookup>" --json`
  for codebase facts.
- The main question is whether to adopt, replace, upgrade, or compare
  dependencies; route back to `/omagy:plan` with an explicit dependency
  decision scope instead of deciding it inside this skill.
- The user only needs implementation against already-grounded requirements; use
  `/omagy:ralph`, `/omagy:team`, or the direct executor lane as appropriate.
- The task can be answered from stable local project conventions without
  current external lookup.

## Specialist Routing

1. Use `omagy explore --prompt "<narrow lookup>" --json` first for brownfield
   facts: current code usage, local constraints, versions, config, and
   integration points.
2. Use the Antigravity/Omagy researcher lane when available for
   official/upstream docs, release notes, standards, migration guides,
   source-backed examples, and current best-practice evidence for an already
   chosen technology.
3. If no dedicated researcher lane is available, use the normal external
   research path, cite official/upstream URLs, and explicitly mark any evidence
   gap. Do not invent authority from memory.
4. Route dependency adoption, upgrade, replacement, or comparison decisions
   back to `/omagy:plan` as a dependency decision; this skill may provide
   source evidence but does not choose the dependency.
5. Return to the caller with explicit evidence, uncertainty, and any
   implementation handoff constraints.

## Source-Quality Rules

- Prefer official documentation, upstream source, release notes, changelogs,
  standards, and maintainer guidance.
- Include source URLs for material claims.
- State date/version context for current best-practice claims.
- Label third-party summaries as supplemental; do not use them before
  official/upstream sources.
- Flag stale, conflicting, undocumented, or version-mismatched evidence.
- Do not over-fetch: gather the smallest evidence set that can support the
  decision.

## Workflow

1. Classify the question: conceptual best practice, implementation guidance,
   migration/version guidance, standards/compliance guidance, or mixed local +
   external guidance.
2. Gather repo-local facts with `omagy explore --prompt "<narrow lookup>" --json`
   when local usage or constraints affect the answer.
3. Gather external evidence with the researcher lane or normal external
   research path when current or version-aware practice affects correctness.
4. Synthesize a concise answer with source quality, version/date context,
   caveats, and an implementation or planning handoff.
5. Stop when the answer is grounded enough for the caller; otherwise report the
   exact blocker or specialist handoff needed.

## Output Contract

```md
## Best-Practice Research: <question>

### Direct Recommendation
<actionable guidance or decision support>

### Evidence Used
- Official/upstream: <source URL> - <what it establishes>
- Supplemental, if any: <source URL> - <why it is secondary>

### Version / Date Context
<versions, dates, release channels, or unknowns>

### Repo-Local Context
<facts from omagy explore, or "not needed">

### Boundaries / Non-goals
<what this research does not decide>

### Handoff
<planning/execution/test implications>
```

## Stop Rules

- Stop after a source-backed recommendation is reusable by the caller.
- Stop and route upward if the task becomes dependency comparison, broad
  architecture, or implementation.
- Do not continue researching when remaining work would only polish wording
  rather than change the recommendation.

Task: {{ARGUMENTS}}

From shayne-snap/oh-my-antigravity, MIT.

More from shayne-snap/oh-my-antigravity