research-to-openspec

What this skill does

# Research-to-OpenSpec Proposal

Convert a complete research or design document into a scoped OpenSpec change
with four artifacts: `proposal.md`, delta specs, `design.md`, and `tasks.md`.

Research documents are comprehensive but not actionable — they explore the
problem space broadly. OpenSpec changes are narrow and executable — they scope
an MVP, spec the behaviors, record design decisions, and break work into phases.
The gap between the two is where plans go wrong: scope creep, unstated infra
assumptions, and missing wire-format specs. This workflow bridges that gap
systematically.

## When to Invoke

- A research or design doc (typically 20+ pages) already exists
- The user wants to move from "explored" to "scoped and ready to build"
- The doc contains a "MVP Roadmap", "What to Build", or equivalent section
  signaling the author already thought about phasing

Do NOT use this skill when the user is still exploring or brainstorming.
Use `opsx-explore` (if available) for that. This skill assumes the exploration
is done.

## Workflow

### Phase 1 — Gather Context

1. **Read the research doc's MVP section** to extract the author's intended
   minimum scope. This is the ceiling — do not expand beyond it without
   explicit user approval.
2. **Read companion docs** (architecture docs, mockups, design notes) for
   implementation-level detail: message formats, data models, deployment
   topology, transport choices.
3. **Scan existing OpenSpec changes** in `openspec/changes/` to absorb the
   project's style conventions:
   - Proposal format (intent, scope, approach, affected specs, success criteria)
   - Spec scenario structure (`GIVEN`/`WHEN`/`THEN` with `SHALL`)
   - Design decision numbering (`D0`, `D1`, ...)
   - Tasks phase grouping and task-ID pattern (`<phase>.<index>`)

### Phase 2 — Verify Infrastructure Assumptions (Critical)

Fleet plans fail most often on **unstated infrastructure assumptions**, not
logic errors. Before writing any artifact:

4. **Audit the target codebase** for assumptions the research doc makes:
   - Does the workspace layout support the plan? (e.g., does `packages/`
     exist if the plan assumes npm workspaces?)
   - Does the target framework have the hooks, handlers, or event routing
     the plan depends on? (e.g., does `slack.ts` handle slash-commands, or
     only message events?)
   - Does the telemetry/messaging system work as assumed? (e.g., is it
     fire-and-forget or pub-sub?)
   - Are the OAuth scopes, API tokens, and service accounts in place?

Log every assumption and its verification status. Unverified assumptions
become Phase 0 tasks or explicit design decisions with trade-offs.

### Phase 3 — Write the Four Artifacts

Execute these in order. Each artifact builds on the previous one.

5. **`proposal.md`** — Write with these sections:
   - **Intent**: Why this change, why now, link to source research doc
   - **Scope**: Explicit in-scope / out-of-scope lists; scope should match
     or be narrower than the research doc's MVP, never wider
   - **Approach**: High-level direction in 1-2 paragraphs
   - **Affected Specs**: Which capabilities this introduces or modifies
   - **Success Criteria**: Verifiable checklist with `- [ ]` checkboxes;
     each criterion must be testable, not vague

6. **Delta specs** under `specs/<capability>/spec.md` — For each affected
   capability:
   - One requirement per distinct behavior
   - One scenario per requirement using `GIVEN`/`WHEN`/`THEN` + `SHALL`
   - Every mode, type, trigger, and action gets its own scenario — do not
     combine multiple behaviors into one scenario
   - If the research doc describes a wire format or data model, spec it
     with exact field names and types

7. **`design.md`** — Structure as a numbered decision log:
   - Each decision: `### D<N> — <title>`, then **Decision**, **Why**,
     **Alternatives rejected**, **Trade-off** subsections
   - Include a data model section with language-appropriate type definitions
   - Include an ASCII architecture diagram showing component relationships
   - Include a risks table (`| Risk | Mitigation |`)
   - Include an "Open questions (deferred)" section linking to the research
     doc's open questions

8. **`tasks.md`** — Break into phases:
   - **Phase 0**: Infrastructure prep (verify assumptions, set up accounts,
     register API scopes, create feature flags)
   - **Phase 1–N**: Implementation phases, ordered by dependency
   - **Final phase**: Documentation and handoff
   - Each task ID: `<phase>.<index>` (e.g., `0.1`, `1.1`, `2.3`)
   - Each task should be atomic enough for a single agent session
   - Include verification steps inline (not a separate "testing" phase)

### Phase 4 — Post-Generation

9. **Recommend adversarial review**: After writing all artifacts, prompt the
   user to run `resilient-flows:adversarial-plan-review` (if available in the
   current session). This dispatches a fresh reviewer agent that catches infra
   assumption gaps the planner is anchored to. Especially valuable for plans
   that cross machine boundaries or assume framework capabilities. If the
   skill is not installed, recommend a manual review focused on Phase 2's
   infrastructure assumptions.

## Key Principles

- **MVP ceiling, not floor**: The research doc's MVP section defines the
  maximum scope. Trim from there if needed; never add.
- **Verify, don't assume**: Every infrastructure dependency gets checked
  against the actual codebase before it enters the plan.
- **One scenario per behavior**: Spec scenarios are the contract the
  implementation is tested against. Combining behaviors obscures failures.
- **Decisions, not descriptions**: `design.md` records choices made and
  alternatives rejected. It is not a restatement of the research.
- **Tasks for agents, not humans**: Each task should be self-contained
  enough that an automated execution loop (`/opsx-apply` or similar) can
  execute it without additional context.

## Additional Resources

### Reference Files

For detailed guidance on artifact formatting and common pitfalls:
- **`references/artifact-conventions.md`** — Detailed formatting conventions
  for each artifact, with examples from real OpenSpec changes