Turn an Agreed Conversation Into a Spec

What it does

This user-invoked workflow is synthesis rather than a new interview. It reads the current project state, uses the domain glossary and respects recorded architecture decisions. Before publishing, it checks that the proposed test seams match the user’s expectations, preferring existing high-level surfaces. Its output covers the user problem, solution, extensive user stories, implementation decisions, testing decisions, exclusions and further notes. The default source flow publishes the result to the configured issue tracker with the ready-for-agent label.

When to use it

• A detailed planning conversation needs a durable implementation brief.
• An agreed prototype decision should become a ticket-ready requirement.
• A feature needs explicit scope and testing decisions before work is delegated.

Step-by-step workflow

1. Review the existing conversation, relevant code, glossary and ADRs without restarting discovery.
2. Identify existing high-level test seams that can exercise the required behavior.
3. Confirm those seams with the user before finalizing the specification.
4. Write the problem, solution, user stories, decisions, test plan and out-of-scope behavior.
5. Publish through the configured tracker workflow with the appropriate label when authorized.

Example request

Use to-spec to capture the refund feature we have already agreed. Use our glossary terms and preserve the decision that partial refunds are supported while store credit is out of scope. Propose the public test seam for success, duplicate submission and provider failure, and confirm it before finalizing. Include user stories, implementation and testing decisions without speculative file paths. Prepare a local reviewable spec first; do not publish to the tracker until authorized.

Worked example

If a conversation agreed partial refunds but never discussed store credit, the spec should not silently add a credit ledger. The acceptance stories can describe a remaining refundable balance, duplicate request behavior and a provider failure. Testing decisions should identify the observable refund result rather than private helper methods. A prototype’s concise state-machine snippet can be retained when it communicates a settled decision more precisely than prose; most file paths and incidental code should stay out of the spec.

What you get

A structured feature specification ready for review and, with appropriate authorization, publication to the project tracker.

How to evaluate the result

• Trace user stories to decisions actually made in the conversation.
• Confirm exclusions and failure cases are explicit.
• Check agreed test seams and review the destination before tracker publication.

What you need

An already developed feature discussion, codebase context, glossary, ADRs and configured tracker/label vocabulary. User availability is needed to confirm test seams.

Setup and activation

The publisher documents plugin setup for Claude Code, Codex and Copilot, and manual Agent Skills setup for Gemini CLI and other clients. Choose one distribution method per client to avoid duplicate skills. The engineering collection expects project-specific tracker, triage-label and document-location settings from setup-matt-pocock-skills. Keep referenced companion skills and files available. This catalogue review does not install or run them; scan the exact source before any later installation. Client tools, permissions and subagent support still need separate validation.

Limits and considerations

The source says not to restart the interview, but still requires agreement on test seams. Incomplete prior decisions should remain explicit rather than invented. The default upstream flow writes to the tracker, so invocation must fit the user’s actual publishing authorization. A spec does not itself implement or test the feature.

Related workflows

• Use grill-with-docs when key requirements are still unresolved.
• Use implement-spec after tickets and blocking relationships have been prepared.

License and reuse

MIT at repository level (Copyright 2026 Matt Pocock). Preserve the copyright and permission notice when redistributing substantial source material; inspect any separately licensed dependencies or assets.

Further reading

• Publisher README: client setup and companion skills
• Reviewed SKILL.md (immutable commit)
• Reviewed MIT license