---
title: "Conversation to Specification: review, setup & limitations · Undominated.ai"
canonical: https://undominated.ai/skills/mattpocock-to-spec/
description: "Turns an already-discussed change into a repository-aware specification for the configured issue tracker."
---

# Conversation to Specification: review, setup & limitations · Undominated.ai

> Turns an already-discussed change into a repository-aware specification for the configured issue tracker.

[← Explore all skills](/skills/)

PLANNING AND DELIVERY / Matt Pocock

# Conversation to Specification

Turns an already-discussed change into a repository-aware specification for the configured issue tracker.

 [See setup guidance ↓](#setup)[Original source ↗](https://github.com/mattpocock/skills/blob/49dd158d1076134a641b33efb035946536778336/skills/engineering/to-spec/SKILL.md)

SOURCE REVIEW

 Reviewed 2026-10-15
 Evidence 16 linked sources
 Publisher Matt Pocock
 Licence [MIT ↗](https://github.com/mattpocock/skills/blob/49dd158d1076134a641b33efb035946536778336/LICENSE)
 Revision 49dd158d1076
 [Read what was—and wasn’t—checked ↓](#review)

“Turn the current conversation into a spec and publish it to the project issue tracker: no interview, just synthesis of what you've already discussed.”

 [Matt Pocock · upstream description ↗](https://github.com/mattpocock/skills/blob/49dd158d1076134a641b33efb035946536778336/skills/engineering/to-spec/SKILL.md) Our analysis follows below.

01 / THE REASONING

## Why this made the selection.

 - Uses existing project context, glossary and architecture decisions before synthesizing requirements.
- Makes scope exclusions, implementation boundaries and test seams explicit instead of treating a discussion transcript as a specification.

### A good fit for

 - Converting an agreed design conversation into an implementable issue
- Keeping terminology and prior architecture decisions consistent across a handoff
- Agreeing the test seams for a feature before the spec is published
- Preserve a prototype state machine, reducer, schema or type shape when it expresses a specification decision more precisely than prose.

### Weigh up before choosing

 - This is synthesis after discussion, not a discovery interview or a check that every stakeholder requirement is present.
- Invocation can publish to the configured tracker and apply a readiness label; review confidential content and the destination first. The label is not evidence that implementation will succeed.
- The setup companion edits repository guidance and tracker configuration; it is a separate workflow that should be inspected.
- The download carries SKILL.md and agents/openai.yaml. The skill expects the tracker and label vocabulary that setup-matt-pocock-skills writes. Without them it tells the user to run setup-matt-pocock-skills, which is not in the download.

02 / THE REVIEW RECORD

## What we actually inspected.

Source review has boundaries. A clear record is more useful than a “safe” badge.

### Material inspected

 - skills/engineering/to-spec/SKILL.md
- README.md (installation and setup sections; the README has no licence section)
- LICENSE (MIT, copyright 2026 Matt Pocock)
- skills/engineering/to-spec/agents/openai.yaml
- skills/engineering/setup-matt-pocock-skills/SKILL.md
- skills/engineering/setup-matt-pocock-skills/agents/openai.yaml
- skills/engineering/setup-matt-pocock-skills/domain.md
- skills/engineering/setup-matt-pocock-skills/issue-tracker-github.md
- skills/engineering/setup-matt-pocock-skills/issue-tracker-gitlab.md
- skills/engineering/setup-matt-pocock-skills/issue-tracker-local.md
- skills/engineering/setup-matt-pocock-skills/triage-labels.md

### Our findings

 - The entry disables implicit invocation and has a matching Codex invocation policy.
- The setup companion supports GitHub, GitLab and local Markdown; the full companion and its tracker/domain templates were read.
- Before writing, the agent sketches the test seams, prefers existing seams and the highest one ('the ideal number is one'), and checks them with the user. It then publishes the spec and applies the ready-for-agent label without further triage.
- The spec template runs from Problem Statement to Further Notes, asks for an extensive numbered list of user stories, and bars file paths and code snippets except a decision-encoding snippet from a prototype.
- Re-pinned from c55ee46073ed923f86ce59a5eb3b6d895095d1b7 to 49dd158d1076134a641b33efb035946536778336: to-spec/SKILL.md and agents/openai.yaml are unchanged. The setup companion now names GLOSSARY.md instead of CONTEXT.md. At this revision the setup companion also creates any configured triage label the GitHub or GitLab tracker lacks (gh label create / glab label create), when the triage skill is installed.

### Not established by this review

 - No upstream definition, helper, installer or generated workload was executed.
- No end-to-end agent session or effectiveness benchmark was run.
- Not executed: it was not installed or run.

The review applies to the material and revision named here. A newer upstream release can change its behavior.

03 / PUT IT TO WORK

## Add a skill to your workflow.

[Upstream setup instructions ↗](https://github.com/vercel-labs/skills/blob/7407f3893ad4dceab546ac002c3ef806e4000c73/README.md)

DOCUMENTED COMMAND

 npx skills add mattpocock/skills --skill to-spec --skill setup-matt-pocock-skills Copy command ↗

Run in your terminal to choose your AI tools, project or global scope, and installation method. This short command follows the current upstream version; the review covers the revision shown above.

 Optional: install the reviewed revision

Keeps the original source and installer version where recorded, while leaving your AI tools and installation scope for you to choose.

 npx skills add https://github.com/mattpocock/skills/tree/49dd158d1076134a641b33efb035946536778336 --skill to-spec --skill setup-matt-pocock-skills Copy reviewed-revision command ↗ - Install the complete skill directory, including its references and helpers; select your AI tools and project or global scope.
- Run the setup companion once. Inspect its proposed edits to AGENTS.md or CLAUDE.md and docs/agents/ before accepting; it configures GitHub, GitLab or local Markdown tracking. At this revision the setup companion also creates any configured triage label the GitHub or GitLab tracker lacks (gh label create / glab label create), when the triage skill is installed.
- Review the instructions before invoking them. The source revision shown here is the one reviewed; the installer was not executed or version-pinned by this review.
- For manual installation instead, download the complete bundle from https://undominated.ai/resources/skills/mattpocock-to-spec/bundle.zip and extract it into a new directory. It holds SKILL.md and agents/openai.yaml unchanged at revision 49dd158d, the upstream licence and an attribution file.
- Place the extracted directory in your host's documented skills directory, named to-spec. Keep SKILL.md and the licence together.

### Before you start

 - Node.js/npm and git for the documented Skills installer
- An agent host that supports the skill format and the tools required by the workflow
- Configured tracker access: authenticated gh or glab for remote issues, or a writable local Markdown directory

### Compatibility

Claude Code · Codex · GitHub Copilot · Gemini CLI

### Repository instructions and host-provided tools

 - Read the current conversation, repository context and architecture decisions
- Write a local specification or create an issue using configured tracker credentials
- The separately invoked setup companion updates repository instruction/configuration files and can create missing triage labels on GitHub or GitLab

### Cost model

MIT-licensed instructions; agent usage and any issue-tracker account terms are separate.

THE COMPLETE REVIEWED DEFINITION

## Read it before you reuse it.

Original source bytes, with attribution. Review the host-specific setup notes above.

 Copy definition ↗ [Download complete resource + licence ↗](/resources/skills/mattpocock-to-spec/bundle.zip)[Raw Markdown ↗](/resources/skills/mattpocock-to-spec/definition.md)
 ---
name: to-spec
description: "Turn the current conversation into a spec and publish it to the project issue tracker: no interview, just synthesis of what you've already discussed."
disable-model-invocation: true
---

This skill takes the current conversation context and codebase understanding and produces a spec. Do NOT interview the user; just synthesize what you already know.

The issue tracker and triage label vocabulary should have been provided to you. If not, tell the user to run `/setup-matt-pocock-skills`.

## Process

1. Explore the repo to understand the current state of the codebase, if you haven't already. Use the project's domain glossary vocabulary throughout the spec, and respect any ADRs in the area you're touching.

2. Sketch out the seams at which you're going to test the feature. Existing seams should be preferred to new ones. Use the highest seam possible. If new seams are needed, propose them at the highest point you can. The fewer seams across the codebase, the better - the ideal number is one.

Check with the user that these seams match their expectations.

3. Write the spec using the template below, then publish it to the project issue tracker. Apply the `ready-for-agent` triage label - no need for additional triage.

<spec-template>

## Problem Statement

The problem that the user is facing, from the user's perspective.

## Solution

The solution to the problem, from the user's perspective.

## User Stories

A LONG, numbered list of user stories. Each user story should be in the format of:

1. As an <actor>, I want a <feature>, so that <benefit>

<user-story-example>
1. As a mobile bank customer, I want to see balance on my accounts, so that I can make better informed decisions about my spending
</user-story-example>

This list of user stories should be extremely extensive and cover all aspects of the feature.

## Implementation Decisions

A list of implementation decisions that were made. This can include:

- The modules that will be built/modified
- The interfaces of those modules that will be modified
- Technical clarifications from the developer
- Architectural decisions
- Schema changes
- API contracts
- Specific interactions

Do NOT include specific file paths or code snippets. They may end up being outdated very quickly.

Exception: if a prototype produced a snippet that encodes a decision more precisely than prose can (state machine, reducer, schema, type shape), inline it within the relevant decision and note briefly that it came from a prototype. Trim to the decision-rich parts, not a working demo, just the important bits.

## Testing Decisions

A list of testing decisions that were made. Include:

- A description of what makes a good test (only test external behavior, not implementation details)
- Which modules will be tested
- Prior art for the tests (i.e. similar types of tests in the codebase)

## Out of Scope

A description of the things that are out of scope for this spec.

## Further Notes

Any further notes about the feature.

</spec-template>

The download contains SKILL.md . Extract the whole bundle; the supporting files are required. Inspect the included MANIFEST.json for file hashes.

By **Matt Pocock**. [Exact upstream source ↗](https://github.com/mattpocock/skills/blob/49dd158d1076134a641b33efb035946536778336/skills/engineering/to-spec/SKILL.md) · [Licence](/resources/skills/mattpocock-to-spec/LICENSE.txt) · [Attribution](/resources/skills/mattpocock-to-spec/ATTRIBUTION.txt)

SHA-256 43ad9cf318e5e7d3d1fa360253a37021796dc87a0c2e595ad262661a10f85088

 Read the applicable licence MIT License

Copyright (c) 2026 Matt Pocock

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

04 / FOLLOW THE EVIDENCE

## The source trail.

Our notes are separate from the original resource. Check upstream before adopting a new version.

 - [Definition at the reviewed revision ↗](https://github.com/mattpocock/skills/blob/49dd158d1076134a641b33efb035946536778336/skills/engineering/to-spec/SKILL.md) Checked 2026-10-13 https://github.com/mattpocock/skills/blob/49dd158d1076134a641b33efb035946536778336/skills/engineering/to-spec/SKILL.md Supports: summary, upstreamDescription, whySelected, bestFor, limitations, review, access
- [Publisher installation and compatibility guidance ↗](https://github.com/mattpocock/skills/blob/49dd158d1076134a641b33efb035946536778336/README.md) Checked 2026-10-13 https://github.com/mattpocock/skills/blob/49dd158d1076134a641b33efb035946536778336/README.md Supports: install, compatibility
- [Licence at the reviewed revision ↗](https://github.com/mattpocock/skills/blob/49dd158d1076134a641b33efb035946536778336/LICENSE) Checked 2026-10-13 https://github.com/mattpocock/skills/blob/49dd158d1076134a641b33efb035946536778336/LICENSE Supports: license, access.cost
- [Reviewed companion: skills/engineering/to-spec/agents/openai.yaml ↗](https://github.com/mattpocock/skills/blob/49dd158d1076134a641b33efb035946536778336/skills/engineering/to-spec/agents/openai.yaml) Checked 2026-10-13 https://github.com/mattpocock/skills/blob/49dd158d1076134a641b33efb035946536778336/skills/engineering/to-spec/agents/openai.yaml Supports: review
- [Skills installer: README.md ↗](https://github.com/vercel-labs/skills/blob/7407f3893ad4dceab546ac002c3ef806e4000c73/README.md) Checked 2026-10-13 https://github.com/vercel-labs/skills/blob/7407f3893ad4dceab546ac002c3ef806e4000c73/README.md Supports: install
- [Skills installer: src/git.ts ↗](https://github.com/vercel-labs/skills/blob/7407f3893ad4dceab546ac002c3ef806e4000c73/src/git.ts) Checked 2026-10-13 https://github.com/vercel-labs/skills/blob/7407f3893ad4dceab546ac002c3ef806e4000c73/src/git.ts Supports: install
- [Skills installer: src/source-parser.ts ↗](https://github.com/vercel-labs/skills/blob/7407f3893ad4dceab546ac002c3ef806e4000c73/src/source-parser.ts) Checked 2026-10-13 https://github.com/vercel-labs/skills/blob/7407f3893ad4dceab546ac002c3ef806e4000c73/src/source-parser.ts Supports: install
- [Reviewed companion: skills/engineering/setup-matt-pocock-skills/SKILL.md ↗](https://github.com/mattpocock/skills/blob/49dd158d1076134a641b33efb035946536778336/skills/engineering/setup-matt-pocock-skills/SKILL.md) Checked 2026-10-13 https://github.com/mattpocock/skills/blob/49dd158d1076134a641b33efb035946536778336/skills/engineering/setup-matt-pocock-skills/SKILL.md Supports: review, limitations, install, access
- [Reviewed companion: skills/engineering/setup-matt-pocock-skills/agents/openai.yaml ↗](https://github.com/mattpocock/skills/blob/49dd158d1076134a641b33efb035946536778336/skills/engineering/setup-matt-pocock-skills/agents/openai.yaml) Checked 2026-10-13 https://github.com/mattpocock/skills/blob/49dd158d1076134a641b33efb035946536778336/skills/engineering/setup-matt-pocock-skills/agents/openai.yaml Supports: review
- [Reviewed companion: skills/engineering/setup-matt-pocock-skills/domain.md ↗](https://github.com/mattpocock/skills/blob/49dd158d1076134a641b33efb035946536778336/skills/engineering/setup-matt-pocock-skills/domain.md) Checked 2026-10-13 https://github.com/mattpocock/skills/blob/49dd158d1076134a641b33efb035946536778336/skills/engineering/setup-matt-pocock-skills/domain.md Supports: review, limitations, install, access
- [Reviewed companion: skills/engineering/setup-matt-pocock-skills/issue-tracker-github.md ↗](https://github.com/mattpocock/skills/blob/49dd158d1076134a641b33efb035946536778336/skills/engineering/setup-matt-pocock-skills/issue-tracker-github.md) Checked 2026-10-13 https://github.com/mattpocock/skills/blob/49dd158d1076134a641b33efb035946536778336/skills/engineering/setup-matt-pocock-skills/issue-tracker-github.md Supports: review, limitations, install, access
- [Reviewed companion: skills/engineering/setup-matt-pocock-skills/issue-tracker-gitlab.md ↗](https://github.com/mattpocock/skills/blob/49dd158d1076134a641b33efb035946536778336/skills/engineering/setup-matt-pocock-skills/issue-tracker-gitlab.md) Checked 2026-10-13 https://github.com/mattpocock/skills/blob/49dd158d1076134a641b33efb035946536778336/skills/engineering/setup-matt-pocock-skills/issue-tracker-gitlab.md Supports: review, limitations, install, access
- [Reviewed companion: skills/engineering/setup-matt-pocock-skills/issue-tracker-local.md ↗](https://github.com/mattpocock/skills/blob/49dd158d1076134a641b33efb035946536778336/skills/engineering/setup-matt-pocock-skills/issue-tracker-local.md) Checked 2026-10-13 https://github.com/mattpocock/skills/blob/49dd158d1076134a641b33efb035946536778336/skills/engineering/setup-matt-pocock-skills/issue-tracker-local.md Supports: review, limitations, install, access
- [Reviewed companion: skills/engineering/setup-matt-pocock-skills/triage-labels.md ↗](https://github.com/mattpocock/skills/blob/49dd158d1076134a641b33efb035946536778336/skills/engineering/setup-matt-pocock-skills/triage-labels.md) Checked 2026-10-13 https://github.com/mattpocock/skills/blob/49dd158d1076134a641b33efb035946536778336/skills/engineering/setup-matt-pocock-skills/triage-labels.md Supports: review, limitations, install, access
- [Pinned definition rechecked for the 2026-10-15 resource wave ↗](https://raw.githubusercontent.com/mattpocock/skills/49dd158d1076134a641b33efb035946536778336/skills/engineering/to-spec/SKILL.md) Checked 2026-10-15 https://raw.githubusercontent.com/mattpocock/skills/49dd158d1076134a641b33efb035946536778336/skills/engineering/to-spec/SKILL.md Supports: bestFor, review
- [Pinned publisher installation text rechecked for the 2026-10-15 resource wave ↗](https://raw.githubusercontent.com/mattpocock/skills/49dd158d1076134a641b33efb035946536778336/README.md) Checked 2026-10-15 https://raw.githubusercontent.com/mattpocock/skills/49dd158d1076134a641b33efb035946536778336/README.md Supports: limitations

KEEP COMPARING

## Other approaches to consider.

Related by category or shared topics. These are alternatives to inspect, not a measured quality order.

 [### Specification to Dependency-Aware Tickets ↗ Splits an agreed plan into small vertical slices, with explicit blocking relationships and a review before publication.](/skills/mattpocock-to-tickets/)[### Conventional Branch ↗ Creates and validates Git branches against the Conventional Branch specification — feature/, bugfix/, hotfix/, release/, chore/ — with a validation ruleset, an invalid-example table, trunk detection and a mapping to Conventional Commits.](/skills/github-conventional-branch/)[### GitHub Release Workflow ↗ Cuts a library release end to end: tag-derived versioning, code-diff-first SemVer analysis against commit intent, Keep a Changelog authoring, and a gated release-branch plus PR handoff.](/skills/github-github-release/)

 [AI Tools ↗](/tools/)[Skills ↗](/skills/)[Agents ↗](/agents/)[MCP Servers ↗](/mcp-servers/)[Workflows ↗](/workflows/)

## Continue your investigation

 - [Choose a toolkit](/tools/)
- [Inspect execution hosts](/agents/)
- [Check tool access](/mcp-servers/)
- [Check project dependencies](/check-repo/)
