Maestro Research Agent Skill

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

• 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.

• 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.

• 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.

• 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:

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:

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.