to-spec

name	to-spec
description	Turn explicitly designated input documents into an approved implementation spec in a per-spec folder under .context/specs. Use when the user explicitly invokes $to-spec with local or attached documents, documentation URLs, or pasted Markdown and wants uncertainties resolved through a one-question-at-a-time interview before the spec is written.

To Spec

Create a standalone spec from explicit inputs and answers gathered during this skill. Do not use conversation history from before the invocation as requirements context. Do not implement the work or publish the spec to an issue tracker.

Input contract

• Require at least one source explicitly identified as input in the invocation or a follow-up response.
• Accept local paths, attached documents, documentation URLs, and pasted Markdown.
• Treat paths as relative to the current working directory unless the user provides an absolute path.
• Do not infer that unrelated open files or previously mentioned documents are inputs.
• If no input is provided, ask for one source and wait.
• If a source is missing, inaccessible, or unreadable, identify it and ask for a replacement. Do not guess its contents.

Example invocations:

$to-spec input: docs/new-form.md
$to-spec inputs: docs/brief.md, https://example.com/api-design
$to-spec input:
## Feature idea
...

Process

1. Read and investigate

1. Resolve and read every designated input. For a long source, inspect its structure and systematically read all sections relevant to requirements, constraints, decisions, and exclusions.
2. Use the inputs as the initial requirements context. Use only answers produced during this skill to supplement them.
3. Explore the repository for discoverable facts: current behavior, domain vocabulary, applicable ADRs, existing interfaces, constraints, and test patterns. Repository evidence may clarify implementation facts but must not silently invent or override product requirements.
4. If the target .context/specs/<spec-slug>/SPEC.md already exists, read it as another input before proposing changes.

2. Resolve every material doubt

Build an internal decision tree from the inputs and repository evidence. Resolve dependencies before downstream choices.

• Look up discoverable facts instead of asking the user.
• Ask about product intent, trade-offs, ambiguous scope, conflicting sources, and decisions that cannot be discovered.
• Ask exactly one question at a time and wait for the answer.
• Include a concrete recommended answer and its main trade-off with every question.
• Never silently choose between conflicting inputs.
• Continue when an answer exposes another unresolved branch.
• Avoid questions that do not materially affect the spec.

Do not proceed while any material decision, conflict, or acceptance criterion remains unresolved.

3. Confirm shared understanding

When no material doubts remain, present a concise synthesis covering:

• The user problem and intended outcome
• The agreed solution and important behavior
• Major implementation decisions and constraints
• Test seams and acceptance criteria
• Explicit exclusions
• The proposed .context/specs/<spec-slug>/SPEC.md path

Ask for explicit confirmation that this shared understanding is correct. If the user changes or rejects anything, return to the one-question-at-a-time loop. Do not create directories or write files before confirmation.

4. Write the spec

After confirmation:

1. Derive <spec-slug> from the approved title using lowercase kebab-case. Ask during the interview if more than one clear slug is plausible.
2. Create .context/ and .context/specs/ only if missing. Preserve all unrelated content already under .context/.
3. Create or update .context/specs/<spec-slug>/SPEC.md using the structure below.
4. When updating an existing spec, revise the standard sections to match the confirmed understanding. Preserve unrecognized or manually added sections unless the user explicitly approved their removal.
5. Make the document understandable without access to the conversation.

Use this structure:

# <Spec title>

## Inputs

List each input path, attachment name, URL, or inline-input label and briefly state its role.

## Problem Statement

Describe the problem from the user's perspective.

## Solution

Describe the agreed solution from the user's perspective.

## User Stories

Provide a thorough numbered list in the form: "As a <user>, I want <capability>, so that <benefit>." Cover relevant actors, primary flows, edge cases, and failure behavior.

## Implementation Decisions

Record approved architecture, module boundaries, interfaces, schemas, contracts, interactions, compatibility requirements, and technical constraints. Do not include volatile file paths or code snippets. Exception: include only the decision-rich portion of a prototype-derived state machine, reducer, schema, or type shape when it communicates an approved decision more precisely than prose, and label it as prototype-derived.

## Testing Decisions

Define externally observable behavior, the highest practical test seams, affected modules or boundaries, relevant prior test patterns in the repository, and acceptance scenarios. Prefer existing seams and propose the fewest new seams possible.

## Out of Scope

List explicit exclusions and deferred work.

## Further Notes

Record resolved source conflicts, important assumptions, migration or compatibility notes, and other context needed by an implementer.

Do not add an unresolved-open-questions section. If an important question is still open, return to the interview instead of writing the spec.

5. Report completion

Return the created or updated spec path and a brief summary of the recorded inputs. Do not create an issue, apply labels, or make implementation changes.