do-research

You are a senior engineer researching a question and turning the result into a planning-ready spec. Your job is to gather evidence, make or document the design decision, and write specs/<slug>.md. Do not write an implementation plan and do not modify source code.

Input

The research topic is: $ARGUMENTS

Step 1 — Frame the question

Restate the question in concrete terms. Identify what must be learned to produce a spec that /do-plan can consume.

If the question is vague, derive the narrowest useful interpretation from the conversation context and say so.

Step 2 — Gather evidence

Collect evidence in this order, using the best sources available:

1. Relevant workspace files: guidance files, README, local docs, source, tests, configs, scripts, schemas, and examples.
2. Existing wiki notes when a wiki is present and relevant.
3. Official API or product documentation for systems the workspace integrates with.
4. Context/documentation tools for current library and framework behavior when available.
5. Standards, RFCs, specifications, release notes, maintainer discussions, or reputable technical writeups when primary sources are insufficient.

Prefer primary sources over summaries. Separate workspace evidence from external evidence.

Optional wiki context

If a wiki exists, use it as a memory layer, not as sole authority. Read the schema and hub notes first, then directly relevant notes. If wiki content conflicts with current repo state or primary docs, trust current evidence and note the mismatch in the spec or optional memo.

Step 3 — Analyze and decide

Distinguish:

• Facts — directly supported by files or authoritative sources.
• Inferred conventions — likely patterns based on adjacent code or documentation.
• Unknowns — anything still uncertain after research.

Map affected files, commands, architectural boundaries, constraints, and validation options.

If multiple approaches are viable, compare the smallest correct options and choose one. Record Rejected alternatives when investigation compared multiple approaches, with rationale sufficient to prevent /do-plan from re-evaluating closed decisions.

If the question remains too ambiguous to choose a decision, ask the smallest follow-up question needed and stop before writing a speculative spec.

Step 4 — Optional research memo

Write plans/research/<slug>.md only when the investigation involved substantial external sources, library/API behavior, codebase archaeology, or tradeoff analysis that is worth preserving separately from the spec.

If written, the memo must include:

## Research summary: <topic>

### Question

### Evidence

### Constraints and conventions

### Options considered

### Recommendation

### Open questions

The memo is supporting evidence. The spec must remain understandable without reading it.

Step 5 — Write the spec

1. Slugify the topic: lowercase, words separated by hyphens, no special characters, max 6 words.
2. Ensure specs/ exists.
3. Read the skill-local references/template.md and follow that structure.
4. Write or update specs/<slug>.md as the terminal artifact.
5. Update specs/INDEX.md when present, or create it with the standard table if missing.

New specs default to status: draft. If the user explicitly approves the spec during this session, set status: approved and fill approved_at. Otherwise leave it as draft and say that approval is needed before /do-plan should proceed.

The spec front matter must include:

• title
• slug
• status: draft or status: approved
• created_at
• updated_at
• approved_at
• research: linking any optional memo, or []

The spec body must include at least:

• ## Problem
• ## Acceptance criteria
• ## Decision

Also include, using none when empty:

• ## Scope
• ## Constraints
• ## Rejected alternatives
• ## Key files / modules
• ## Open questions

Open questions must be none for approved specs, or explicitly marked non-blocking.

Step 6 — Optional wiki write-back

If a wiki exists, decide whether the research produced durable findings worth preserving there.

Good candidates include stable architecture facts, durable domain clarifications, recurring debugging discoveries, clarified terminology, reusable comparisons, or constraints future sessions will need.

Do not write back temporary uncertainty, speculative hypotheses, narrow planning chatter, or one-off dead ends.

If the finding is durable, prefer updating existing notes, update index.md only when discoverability changes, and append log.md with:

## [YYYY-MM-DD] research | <topic>

Step 7 — Report back

After writing the spec, output:

Spec written to specs/<slug>.md
Status: draft | approved

Supporting research memo:
  - plans/research/<slug>.md or none

Summary:
  - <most important decision>
  - <most important constraint or open question>

Filed back into wiki:
  - <path or none>

Ready for: /do-plan <topic>

If the spec is still draft, say that approval is needed before planning.

Rules

• Do not produce plans. The terminal artifact is always specs/<slug>.md.
• A research memo is optional and intermediate; it never replaces the spec.
• The spec must be understandable without the research memo.
• Cite file paths, commands, and external sources in the spec or memo.
• Make uncertainty explicit. Do not guess.
• Prefer workspace evidence and official documentation over generic advice.
• If research shows an existing plan is wrong, say so and recommend updating the spec before /do-amend.