| name | piper-draft-spec |
| description | Turn a rough idea, brief, or conversation into a properly-formed feature spec / PRD — with problem statement, goals, non-goals, user stories, requirements, open questions, and success criteria. Piper grounds the spec in your project context. Trigger phrases: "write a spec for", "draft a PRD", "spec this out", "write this up properly", "I want to build X". |
draft-spec
Turn a rough idea into a complete, reviewable feature spec — structured so engineers can build from it and stakeholders can approve it without a meeting.
The difference from just asking Piper: this skill produces a consistent output shape (every section present, every non-goal explicit, every open question surfaced) and grounds the spec in your project context (team patterns, current sprint, existing infrastructure) rather than writing a generic document.
When to Use
- PM has an idea and wants it written up properly before handing it to engineering
- You're planning a feature and want to flush out scope, non-goals, and open questions
- You need a shareable artifact for stakeholder review or team alignment
- You want to create GitHub issues from a spec (use
draft-issue for each requirement chunk after the spec is done)
Not for: quick one-off tasks (use draft-issue directly). Not for architecture decisions (use ADR process). Not for bug fixes (use draft-issue).
The Core Insight
A spec's most valuable sections aren't the requirements — they're the non-goals and open questions. Requirements tell engineers what to build; non-goals tell them what to push back on; open questions tell them where to stop and ask rather than guess. Most AI-generated specs skip both. Don't.
Procedure
Step 1 — Gather the brief
Start from whatever PM has: one sentence, a conversation, a rough list, a prototype description. Read it fully. Identify what's clear and what's ambiguous.
Ask PM for the following if not already known:
- Who is the primary user? (which persona, role, or segment)
- What's the one-sentence version of what changes for them?
- Are there constraints you know about? (tech debt, timeline, dependencies)
- Is there a milestone this belongs to?
Don't ask about things you can infer: if PM is talking about a PM feature, the user is probably a PM. If the conversation mentions a sprint, note the milestone. Keep the ask short — 1-3 questions max.
Step 2 — Load Piper context
Before drafting, pull what Piper knows that's relevant. If you have access to Piper's profile data:
- Current active projects and their state
- Team members and their roles
- Existing related features and how they work
- Current sprint focus and what's in flight
If running natively (no server access): use conversation context + your knowledge of this PM's domain. Note what you couldn't verify.
Step 3 — Generate the SLUG and title
SLUG = short uppercase hyphenated label for the feature area. 2–4 words, 15 chars max. Same convention as draft-issue.
Examples:
- "Add AI-powered backlog triage" →
AI-TRIAGE
- "Onboarding flow for first-time PMs" →
PM-ONBOARDING
- "Weekly digest email" →
WEEKLY-DIGEST
Title format: SLUG — Full descriptive name
Step 4 — Draft the spec
Use the template below. Every section is mandatory — write "None identified" or "N/A" rather than leaving a section blank. Omissions make the spec look incomplete even when it isn't.
# SLUG — Full feature name
**Status**: DRAFT
**Author**: [PM name]
**Created**: [date]
**Milestone**: [MVP | Fast Follow | Post-MVP | Enterprise]
**Related issues**: [#N — title, or "None yet"]
---
## TL;DR
[One paragraph. What is this feature, who is it for, and why does it matter now?
Write this last — it's easier once the rest is done.]
---
## Problem
### Who has this problem?
[Specific user or persona — not "users" generically. E.g.: "First-time PMs who haven't used Piper before and don't know what to ask it."]
### What happens today?
[Concrete description of the current experience — what fails, what's missing, what workaround they use.]
### Why does it matter?
[Impact: what this costs the user or the product. Connect to a metric or outcome if you can.]
### Why now?
[What makes this the right time? Sprint focus, dependency unblocked, PM request, user signal.]
---
## Goals
### Primary goal
[One sentence: the change in user experience this spec delivers.]
### Secondary goals (optional)
- [Additional benefit 1]
- [Additional benefit 2]
---
## Non-goals
[What this spec explicitly does NOT cover. Be specific — "we're not building X" is more useful than silence on X. Every non-goal here prevents a scope conversation later.]
- ❌ [Thing that sounds related but is out of scope]
- ❌ [Follow-on feature that would naturally come next but isn't here]
- ❌ [Edge case that would add complexity without proportionate value]
---
## User stories
[2–5 stories in "As a [persona], I want to [action], so that [outcome]" form.
Keep them user-facing — not implementation steps.]
1. As a [persona], I want to [action], so that [outcome].
2. As a [persona], I want to [action], so that [outcome].
3. [etc.]
---
## Requirements
[Group by logical phase or area. Use checkboxes so these can become GitHub issue acceptance criteria directly.]
### [Area or Phase 1]
- [ ] [Specific, testable requirement — describes observable behavior, not implementation]
- [ ] [Specific, testable requirement]
### [Area or Phase 2]
- [ ] [Specific, testable requirement]
### Edge cases and error handling
- [ ] [What happens when X fails or is missing]
- [ ] [What happens with invalid input]
---
## Design notes
[Wireframes, UX flows, or key interaction decisions — or "None yet; PM/design team to drive." Don't block the spec on design; note what's known and what's open.]
---
## Technical notes
[Relevant existing infrastructure, dependencies, or known constraints — or "No constraints identified." Don't write implementation instructions here; write what engineers need to know to estimate and not hit surprises.]
- [Relevant existing service/component and how it connects]
- [Known dependency or constraint]
- [Or: "No constraints identified. Greenfield."]
---
## Open questions
[Every spec has questions. Surface them here rather than letting engineers discover them mid-build. Each question should have an owner and a "needed by" date if the spec has a timeline.]
| Question | Owner | Needed by |
|---|---|---|
| [Specific question that blocks or significantly changes scope] | [PM / CXO / Lead Dev] | [date or "before kick-off"] |
| [Another question] | [owner] | [date] |
---
## Success criteria
[How will you know this shipped successfully? Binary pass/fail — not "users like it." Prefer measurable or verifiable criteria.]
- [ ] [Observable outcome 1 — can be checked without user research]
- [ ] [Observable outcome 2]
- [ ] User can complete [key flow] without hitting an error
- [ ] [Metric or behavior that confirms the problem is solved]
---
## Out of scope (carry-forward)
[Features or edge cases that came up in discussions and were explicitly parked for a later spec. This is where "not now" goes so it's findable later.]
- [Feature or edge case] — [brief reason for deferral]
- [Or: "None identified"]
Step 5 — Review with PM
Show the draft. Highlight:
- The non-goals you inferred (PM may want to pull some back in)
- The open questions you surfaced (who owns each one)
- Any requirements you flagged as high-complexity or risky
Don't present the spec as final — present it as a working draft for PM's corrections.
Step 6 — Create the artifact
Once PM approves, ask where they'd like to save it — or offer to paste the full spec as text they can copy into their preferred tool (doc, Notion, Confluence, etc.).
If PM is using GitHub Issues: use draft-issue to file each requirement chunk as an issue after the spec is approved.
Format: Markdown is the default — it pastes cleanly into most tools and can become issues directly.
Anti-patterns to avoid
| Don't | Why | Instead |
|---|
| Write requirements as implementation steps | Locks engineers into a solution before they've seen the problem | Write observable behaviors ("user can do X") not methods ("system calls Y API") |
| Skip non-goals | Scope creep happens in the silence | Every obvious adjacent feature gets a ❌ in Non-goals |
| Leave open questions out | Engineers will guess wrong | Surface every unresolved question with an owner |
| Write TL;DR first | You don't know what you've decided yet | Write it last |
| Use vague success criteria ("users feel better") | Can't be verified | Binary, observable, ideally measurable |
| Pad requirements to look thorough | Noise drowns signal | 5 sharp requirements beat 15 vague ones |
| Write a spec for something that needs a 5-minute fix | Over-engineering | Use draft-issue directly for simple, well-understood work |
Quality checklist
Before showing the spec to PM:
Example
Input (from conversation):
"We should have a way for Piper to send me a weekly digest — like a summary of what happened in my product that week. GitHub activity, maybe calendar if it's connected. Something I can read Monday morning."
Note: this example is drawn from Piper's own product development. Product-specific references (feature names, internal roles) are Piper's — substitute your product's equivalents when using this skill.
SLUG: WEEKLY-DIGEST
Draft spec:
# WEEKLY-DIGEST — Weekly product digest delivered Monday morning
**Status**: DRAFT
**Author**: xian
**Created**: 2026-06-15
**Milestone**: Fast Follow
**Related issues**: None yet
---
## TL;DR
A Monday-morning digest that surfaces the prior week's product activity — GitHub commits and closed issues, upcoming calendar items, and any Piper insights that accumulated. PM reads it in 2 minutes and knows where they stand without hunting through GitHub or calendar manually.
---
## Problem
### Who has this problem?
PMs who are context-switching between projects or coming back after weekend/holiday and need a quick re-orientation to what happened and what's coming.
### What happens today?
PM manually checks GitHub notifications, scans their calendar, and reviews Piper conversation history. There's no summary surface — it requires 10–15 minutes of active hunting each Monday.
### Why does it matter?
Monday context-switching is a high-friction moment. A well-timed digest means PM can make a pull request review decision or flag a stalled issue before their first meeting.
### Why now?
GitHub connector is being wired in Wave 1 (meet-piper + connect-piper). Once that's in place, the digest has its data source.
---
## Goals
### Primary goal
PM receives a concise Monday digest that covers GitHub + Calendar activity for the prior week without manual hunting.
### Secondary goals
- Establishes a touchpoint for Piper to proactively surface insights (Trust Gradient stage-gate)
- Creates a natural re-engagement hook for PMs who aren't using Piper daily
---
## Non-goals
- ❌ Real-time notifications or alerts (separate feature; delivery mechanism is different)
- ❌ Customizable digest templates or frequency (start with opinionated defaults)
- ❌ Integrations beyond GitHub and Calendar in v1 (Notion, Slack, Linear are follow-on)
- ❌ Digest archive or search (v1 is delivery only; no UI surface)
---
## User stories
1. As a PM, I want to receive a Monday digest in my Claude conversation, so that I can orient to the week without manually checking GitHub and Calendar.
2. As a PM, I want the digest to include closed issues and merged PRs from the past week, so that I know what shipped without reading every notification.
3. As a PM, I want the digest to include upcoming calendar events for the week, so that I can see what's on my plate alongside what shipped.
---
## Requirements
### Digest generation
- [ ] Piper generates a digest covering the 7-day window ending Sunday 11:59pm
- [ ] GitHub section: closed issues, merged PRs, new issues opened — grouped by repo
- [ ] Calendar section: events for the coming week (Mon–Sun), filtered to work calendars
- [ ] Insights section: any Piper insights that emerged in the prior week (if assistant has sufficient session context)
### Delivery
- [ ] Digest is delivered as a Piper message (in conversation, not email — v1)
- [ ] PM can trigger it manually ("send me my weekly digest") or it fires automatically Monday morning if a cron mechanism is available
- [ ] If a connector (GitHub, Calendar) is not wired, that section is omitted with a note ("Connect GitHub to include activity — run meet-piper to set up")
### Edge cases and error handling
- [ ] If no GitHub activity in the past week, say so rather than omitting the section
- [ ] If calendar integration is unavailable, omit gracefully with connector-setup note
---
## Design notes
None yet. Digest is text-only in v1 — no UI surface, no email template. Format: markdown sections with headers, brief bulleted lists, total <300 words.
---
## Technical notes
- Depends on: GitHub connector (meet-piper Wave 1), Calendar connector (meet-piper Wave 1 if wired)
- Data fetch: same enrichment layer as consult-piper, called on a Monday cron or user trigger
- Piper insights: read from session history and stored PM profile — included when enough context exists
---
## Open questions
| Question | Owner | Needed by |
|---|---|---|
| Is Monday delivery via cron or manual trigger only in v1? | xian | Before kick-off |
| Which calendar provider(s) are in scope for v1 — Google only, or also Outlook? | xian | Before kick-off |
| Does the digest go into the main conversation thread or a dedicated channel? | PM/design lead | Before design |
---
## Success criteria
- [ ] PM can request "send me my weekly digest" and receive a correctly structured digest
- [ ] GitHub section accurately reflects closed issues and merged PRs from the prior 7 days
- [ ] If no connectors are wired, digest gracefully degrades with connector-setup prompts
- [ ] Digest reads in under 2 minutes (length check: ≤300 words)
---
## Out of scope (carry-forward)
- Email delivery — v2; v1 is in-conversation only
- Custom frequency (bi-weekly, daily) — start with weekly; let usage data drive
- Digest archive — no UI surface in v1
Changelog
- v1.0 (2026-06-15): Initial version.
