🥮 skills.mooncakes.ioexperimental

to-spec

// Turn the current conversation, an existing plan, or settled design decisions into a comprehensive specification and publish it to the configured project tracker without reopening the design interview. Use when the user asks to write, synthesize, or publish a spec from context that has already been discussed.

moon runwasm

moon runwasm Yoorkin/to-spec@0.1.0

$ files

SKILL.md

readonly

To Spec

Synthesize what is already known into a specification. Do not restart the interview, invent missing agreement, or silently broaden scope.

The only user checkpoint allowed by default is confirmation of the proposed testing seams. If required information is genuinely absent, mark it explicitly as unresolved rather than conducting a new grilling session.

Resolve the source and destination

Treat the current conversation as the primary source.
If the user supplies a plan, issue, URL, or file, read its full body and relevant comments or linked decisions.
Determine the configured issue tracker and triage vocabulary from repository instructions or available integrations.
If a real tracker is configured, publish there. If none is configured, write one local spec file under .scratch/<feature-slug>/spec.md and report its path; do not block on an unavailable setup skill.
Never overwrite or materially modify an existing issue unless the user identifies it as the publication target.

Ground the specification

Explore the repository enough to understand current behavior, architecture, and prior art.
Read the relevant domain glossary and use its canonical vocabulary throughout.
Read applicable ADRs and preserve their constraints. Surface conflicts instead of silently contradicting them.
Separate settled decisions from assumptions. Do not present an inference as user agreement.

Select testing seams

Sketch where externally observable behavior will be tested.

Prefer existing seams over adding new ones.
Prefer the highest stable seam that verifies behavior without coupling to implementation details.
Minimize the number of seams; one high-leverage seam is ideal when sufficient.
When a new seam is necessary, place it as high as practical.

Show the proposed seams briefly and ask the user whether they match expectations. This is a focused approval, not a new design interview. Incorporate the response before writing the final spec.

Write the specification

Use exactly these top-level sections unless the project enforces a stronger template.

## Problem Statement

<The user's problem, expressed from the user's perspective.>

## Solution

<The agreed solution, expressed from the user's perspective.>

## User Stories

1. As a <specific actor>, I want <observable capability>, so that <user benefit>.

## Implementation Decisions

- <Settled module, interface, architecture, schema, contract, or interaction decision.>

## Testing Decisions

- <What externally observable behavior makes a good test.>
- <Which modules or seams will be tested.>
- <Relevant testing prior art in the codebase.>

## Out of Scope

- <Explicitly excluded work or behavior.>

## Further Notes

<Constraints, accepted risks, follow-ups, or unresolved items not covered above.>

Problem and solution

State the problem before implementation concerns.
Describe the solution in user-visible terms.
Preserve uncertainty where the discussion did not settle an answer.

User stories

Produce a long, numbered, comprehensive set.
Use the form: As a <actor>, I want <feature>, so that <benefit>.
Cover primary flows, alternate actors, permissions, empty states, failure states, recovery, accessibility, migration, rollout, and operationally visible behavior when relevant.
Avoid duplicate stories that merely rephrase the same behavior.

Implementation decisions

Include only decisions already supported by the conversation or repository evidence, such as:

modules to create or modify;
interfaces and contracts;
architectural choices;
schema and migration decisions;
API behavior;
specific cross-system interactions.

Do not include ordinary file paths or working code snippets because they age quickly. A short prototype excerpt is allowed only when it encodes a settled decision more precisely than prose, such as a state machine, reducer, schema, or type shape. Label it as prototype-derived and trim it to decision-rich content.

Testing decisions

Describe tests in terms of external behavior rather than implementation details. Name the selected seams, modules under test, and similar tests already present in the repository.

Scope

List meaningful exclusions explicitly. Do not hide unresolved requirements inside Out of Scope; place them in Further Notes as unresolved.

Publish

Render the final document using the tracker-native issue format or the local fallback path.
Publish one spec artifact, not a collection of fragments.
Apply the configured equivalent of ready-for-agent when using a real tracker and the label exists. Do not invent labels without checking.
Return the issue URL or local path and a concise summary of what was synthesized.