From superspec
Use when a non-engineer (PM / designer / product owner) has opened a frontend PR sketching a new feature's UI and user-flow with mocked data or stubbed API calls, and engineering needs to extract requirements, reason about backend / API support, and produce an OpenSpec change directory ready for ss-writing-plans
How this skill is triggered — by the user, by Claude, or both
Slash command
/superspec:ss-deriving-spec-from-pm-prThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Product owners often communicate new feature ideas by opening a frontend PR with mocked data, draft layouts, or stubbed API calls. The PR shows what the user sees — but the backend does not yet exist, or only partially exists. This skill turns that PR into an OpenSpec change directory (`openspec/changes/YYYY-MM-DD-<topic>/`) ready for `ss-writing-plans` to consume.
Product owners often communicate new feature ideas by opening a frontend PR with mocked data, draft layouts, or stubbed API calls. The PR shows what the user sees — but the backend does not yet exist, or only partially exists. This skill turns that PR into an OpenSpec change directory (openspec/changes/YYYY-MM-DD-<topic>/) ready for ss-writing-plans to consume.
Announce at start: "I'm using the ss-deriving-spec-from-pm-pr skill to turn the PR into a spec."
Core principle: The product-owner-decided UI is input, not a discussion topic. Layout, copy, and user-flow as drafted in the PR are constraints. What gets re-thought is the backend, API contract, data model, validation, error handling, permissions, and cross-service integration.
Do NOT redesign the PR's UI. Do NOT auto-invoke `ss-writing-plans`. Do NOT write implementation steps. This skill ends at producing the change directory; the user decides when to invoke `ss-writing-plans`.Do NOT use when: The author shared only a Figma link, Slack thread, or text idea without a PR — use ss-brainstorming instead.
You MUST create a TodoWrite task for each stage and complete in order. Each stage requires explicit user confirmation before advancing.
ss-writing-plansAsk the user for the PR URL or <owner>/<repo>#<number>. Then:
gh pr view <pr> --json title,body,files,comments,headRefName,baseRefName,url,author
gh pr diff <pr>
Summarize for the user:
Confirm summary with user before proceeding.
From the diff:
sequenceDiagram showing User → Frontend → BackendConfirm the flow with the user. If the user corrects your reading of the UI, update — but never propose UI changes yourself.
For each API call observed in the PR (e.g. fetch, axios, SWR, RTK Query, project-specific API clients):
| Endpoint | Method | Request shape | Response shape (mock?) | Auth / scoping | Pagination | Error cases | Status |
Status column values:
Cross-reference the corresponding backend repo. Use Grep / Read against the backend service to verify (do NOT guess). If the backend follows a layered architecture (e.g., migration / domain / adapter / service / router, or any equivalent split), call out which layers each gap touches.
Reminder: when the work touches multiple services or both FE + BE, recommend splitting into multiple PRs along service seams. Note the recommended split in design.md (under a "PR split plan" subsection).
Use AskUserQuestion to resolve ambiguities. Topics:
Do NOT ask the user about UI / layout / copy. If you catch yourself drafting a UI question, STOP — that's the product owner's call.
Where to write:
openspec/ directory, use itopenspec/, use itDirectory: <repo>/openspec/changes/YYYY-MM-DD-<topic>/
Files:
design.md — scope, architecture, decisions, rationale. Must include:
PR <url>)frontend/src/pages/<Page>.tsx); do NOT redraw or restyle.specs/ — one file per capability:
tasks.md — high-level checklist; one line per major task. ss-writing-plans will expand each into bite-sized steps:# Tasks: <Feature Name>
- [ ] Migration: <table changes>
- [ ] Domain / Models: <pure logic, types>
- [ ] Adapter / Repository: <DB, external API>
- [ ] Service: <orchestration>
- [ ] API / Router: <endpoints>
- [ ] Frontend: wire real API into PR #<num>
(Adjust task names to match the project's architectural vocabulary.)
After writing, scan once: does design.md exist and link the source PR? does tasks.md use - [ ]? If yes, proceed to handoff.
State exactly:
"Spec ready at
<repo>/openspec/changes/YYYY-MM-DD-<topic>/design.md. Backend gaps documented inspecs/. Next step: invokess-writing-plansto produce the implementation plan. I will not invoke it automatically."
Stop. Wait for user.
| ❌ Don't | ✅ Do |
|---|---|
| Redesign the PR's UI | Treat UI / layout / copy as constraint; reference PR component paths |
| Trust the PR's mock API as a backend contract | Challenge every mock; design the real contract in Stage 3 |
| Skip Stage 4 (clarify) | Always run AskUserQuestion before writing design.md |
| Write step-by-step implementation steps | That's ss-writing-plans's job |
Auto-invoke ss-writing-plans | Hand off via text; let the user invoke |
Modify ss-writing-plans or ss-brainstorming | Cross-reference only |
| Bundle FE + BE + migration into one task list | Split along service seams; migrations are typically their own PR |
ss-writing-plans.ss-writing-plans for them" → STOP. Hand off via text only.ss-writing-plans (next step after this skill ends)ss-brainstorming — use that when there is no PRss-writing-skills — TDD-for-skills used to author this skillnpx claudepluginhub coyoteleo/superspec --plugin superspecGuides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.