---
name: reinamaccredy/maestro-research
source: https://app.decimal.ai/s/reinamaccredy-maestro-research@1/SKILL.md
source_sha256: 4e4e6eead311
---

# Maestro Research

Research is breadth. Design is depth. Use this skill to decide whether a card
has enough valid context to enter `maestro-design`.

Research writes a same-card `research.md` receipt or a skip receipt. It does
not lock decisions, write acceptance criteria, finalize handoffs, create tasks,
start implementation, browse by default, or approve build.

Activate with a known session id:
`maestro hook record --event skill_activation --skill maestro-research --session <session_id>`

Exact command signatures live in `reference/cli.md` when present. If the local
binary does not list a verb, do not invent it.

## Route

Use this skill when the request is zero-context, unfamiliar-domain, externally
pasted, stakeholder-heavy, hosting-unclear, or when `maestro-design` lacks fresh
research.

Skip research only with a durable skip receipt when one condition is true:

- the user explicitly says to skip research
- a settled spec is pasted
- fresh same-problem research already exists
- the work is a small local change in a known domain
- context is clearly settled and recorded with evidence

Fresh research means the same card and the same problem statement, `as_of`
within 7 days, unchanged `invalidates_when`, and a still-valid
`READY_FOR_DESIGN` gate or skip.

## Do

1. Anchor the card and hosting.
   Run `maestro status`, then `maestro active`. If the idea is external,
   sandbox-bound, or hosting-unclear, record that before writing into the current
   repo. Use the same card for research and later design. Exploratory ideas may
   start as Idea cards; intended product work may start as proposed Features.
   Completion criterion: one owning card and one Hosting value are named, or the
   gate is not `READY_FOR_DESIGN`.

2. Map current context.
   Search precedent with `maestro grep "<topic>" corpus:memory`, then read the
   pasted source, relevant repo artifacts, and stakeholder facts already
   available. If evidence answers a question, inspect it instead of asking the
   user. Completion criterion: the brief can cite what is known from artifacts,
   what is assumed, and what remains unknown.

3. Write the research receipt.
   Create or update same-card `research.md`. If replacing prior research,
   preserve the old brief as `research.md.bak` or a `Superseded` pointer, and
   add a Maestro note with the reason and changed facts. Keep exactly one
   current `research.md`.

   Required receipt sections:
   - Research Status: `skipped`, `skip_reason`, `skipped_by`
   - Hosting: `current-repo`, `sandbox-repo`, or `external`, with rationale
   - Problem
   - Users / Stakeholders
   - Current Context
   - Constraints
   - Unknowns: Blocking, Important but non-blocking, Safe to defer
   - Assumptions
   - Landscape
   - Recommended First Design Fork
   - Stakeholder Actions
   - Research Validity: `as_of`, `invalidates_when`
   - Gate

   Completion criterion: every required section is present, even when the
   section says `None`.

4. Set the gate.
   Choose exactly one:
   - `READY_FOR_DESIGN`
   - `NEEDS_STAKEHOLDER`
   - `NEEDS_EVIDENCE`
   - `PIVOT`
   - `STOP`

   `READY_FOR_DESIGN` requires no blocking unknowns, no open stakeholder
   actions, compatible hosting, whitelisted skip evidence when skipped, and one
   concrete first design fork. Duplicate or prior-art discovery gates `STOP` or
   `PIVOT` with a pointer to the existing card.

   Completion criterion: the final response names the gate, the durable receipt,
   and the next Maestro route.

## Receipt Rules

Landscape is a map, not a decision. It may list directions such as browser
extension, omnichannel assistant, or dedicated inbox. The first design fork is
one entry question for depth, such as "Where should Copilot live in the Sales
workflow?"

Stakeholder actions have status:

```text
open | resolved | superseded
```

A resolved answer may create new blockers. If a deferred unknown becomes
acceptance-critical during the first design fork, `maestro-design` may bounce
back to this skill.

High-risk user skips are allowed only as user-directed risk:

```text
skipped: true
skipped_by: user
unresolved_risks:
- <security, legal, customer-impacting, or data risk>
```

## Time Box

- Light: one session, gate emitted by end of turn.
- Standard: at most three blocking stakeholder questions, then gate.
- Deep: explicit user opt-in only. Record the escalation if it happens
  midstream.

## Stop

- Do not lock A/B/C decisions.
- Do not write acceptance criteria.
- Do not finalize or reconcile a design handoff.
- Do not create implementation tasks.
- Do not treat chat-only or wrong-repo research as enough for design.
- Do not emit `READY_FOR_DESIGN` without a first design fork.
- Do not put the full receipt contract in Harness; Harness gets only router
  guidance.

## Examples

Use `reference/examples.md` for regression examples, including Sales Copilot,
skip receipts, stale research, and hosting mismatch.

## Hand-off

`READY_FOR_DESIGN` plus compatible hosting -> `maestro-design` reads
`research.md` first.

`NEEDS_STAKEHOLDER` or `NEEDS_EVIDENCE` -> stay on the same card and resolve the
listed blocker.

`PIVOT` -> update the problem statement or create a linked successor.

`STOP` -> preserve the receipt and archive or close the candidate when the
owning lifecycle allows it.