--- name: write-spec description: Write a feature spec or PRD from a problem statement or feature idea. Use when turning a vague idea or user request into a structured document, scoping a feature with goals and non-goals, defining success metrics and acceptance criteria, or breaking a big ask into a phased spec. argument-hint: "" --- # Write Spec > If you see unfamiliar placeholders or need to check which tools are connected, see [CONNECTORS.md](../../CONNECTORS.md). Write a feature specification or product requirements document (PRD). ## Usage ``` /write-spec $ARGUMENTS ``` ## Workflow ### 1. Understand the Feature Ask the user what they want to spec. Accept any of: - A feature name ("SSO support") - A problem statement ("Enterprise customers keep asking for centralized auth") - A user request ("Users want to export their data as CSV") - A vague idea ("We should do something about onboarding drop-off") ### 2. Gather Context Ask the user for the following. Be conversational — do not dump all questions at once. Ask the most important ones first and fill in gaps as you go: - **User problem**: What problem does this solve? Who experiences it? - **Target users**: Which user segment(s) does this serve? - **Success metrics**: How will we know this worked? - **Constraints**: Technical constraints, timeline, regulatory requirements, dependencies - **Prior art**: Has this been attempted before? Are there existing solutions? ### 3. Pull Context from Connected Tools If **~~project tracker** is connected: - Search for related tickets, epics, or features - Pull in any existing requirements or acceptance criteria - Identify dependencies on other work items If **~~knowledge base** is connected: - Search for related research documents, prior specs, or design docs - Pull in relevant user research findings - Find related meeting notes or decision records If **~~design** is connected: - Pull related mockups, wireframes, or design explorations - Search for design system components relevant to the feature If these tools are not connected, work entirely from what the user provides. Do not ask the user to connect tools — just proceed with available information. ### 4. Generate the PRD Produce a structured PRD with these sections. See **PRD Structure** below for detailed guidance on what each section should contain. - **Problem Statement**: The user problem, who is affected, and impact of not solving it (2-3 sentences) - **Goals**: 3-5 specific, measurable outcomes tied to user or business metrics - **Non-Goals**: 3-5 things explicitly out of scope, with brief rationale for each - **User Stories**: Standard format ("As a [user type], I want [capability] so that [benefit]"), grouped by persona - **Requirements**: Categorized as Must-Have (P0), Nice-to-Have (P1), and Future Considerations (P2), each with acceptance criteria - **Success Metrics**: Leading indicators (change quickly) and lagging indicators (change over time), with specific targets - **Open Questions**: Unresolved questions tagged with who needs to answer (engineering, design, legal, data) - **Timeline Considerations**: Hard deadlines, dependencies, and phasing ### 5. Review and Iterate After generating the PRD: - Ask the user if any sections need adjustment - Offer to expand on specific sections - Offer to create follow-up artifacts (design brief, engineering ticket breakdown, stakeholder pitch) ## PRD Structure ### Problem Statement - Describe the user problem in 2-3 sentences - Who experiences this problem and how often - What is the cost of not solving it (user pain, business impact, competitive risk) - Ground this in evidence: user research, support data, metrics, or customer feedback ### Goals - 3-5 specific, measurable outcomes this feature should achieve - Each goal should answer: "How will we know this succeeded?" - Distinguish between user goals (what users get) and business goals (what the company gets) - Goals should be outcomes, not outputs ("reduce time to first value by 50%" not "build onboarding wizard") ### Non-Goals - 3-5 things this feature explicitly will NOT do - Adjacent capabilities that are out of scope for this version - For each non-goal, briefly explain why it is out of scope (not enough impact, too complex, separate initiative, premature) - Non-goals prevent scope creep during implementation and set expectations with stakeholders ### User Stories Write user stories in standard format: "As a [user type], I want [capability] so that [benefit]" Guidelines: - The user type should be specific enough to be meaningful ("enterprise admin" not just "user") - The capability should describe what they want to accomplish, not how - The benefit should explain the "why" — what value does this deliver - Include edge cases: error states, empty states, boundary conditions - Include different user types if the feature serves multiple personas - Order by priority — most important stories first Example: - "As a team admin, I want to configure SSO for my organization so that my team members can log in with their corporate credentials" - "As a team member, I want to be automatically redirected to my company's SSO login so that I do not need to remember a separate password" - "As a team admin, I want to see which members have logged in via SSO so that I can verify the rollout is working" ### Requirements **Must-Have (P0)**: The feature cannot ship without these. These represent the minimum viable version of the feature. Ask: "If we cut this, does the feature still solve the core problem?" If no, it is P0. **Nice-to-Have (P1)**: Significantly improves the experience but the core use case works without them. These often become fast follow-ups after launch. **Future Considerations (P2)**: Explicitly out of scope for v1 but we want to design in a way that supports them later. Documenting these prevents accidental architectural decisions that make them hard later. For each requirement: - Write a clear, unambiguous description of the expected behavior - Include acceptance criteria (see below) - Note any technical considerations or constraints - Flag dependencies on other teams or systems ### Open Questions - Questions that need answers before or during implementation - Tag each with who should answer (engineering, design, legal, data, stakeholder) - Distinguish between blocking questions (must answer before starting) and non-blocking (can resolve during implementation) ### Timeline Considerations - Hard deadlines (contractual commitments, events, compliance dates) - Dependencies on other teams' work or releases - Suggested phasing if the feature is too large for one release ## User Story Writing Good user stories are: - **Independent**: Can be developed and delivered on their own - **Negotiable**: Details can be discussed, the story is not a contract - **Valuable**: Delivers value to the user (not just the team) - **Estimable**: The team can roughly estimate the effort - **Small**: Can be completed in one sprint/iteration - **Testable**: There is a clear way to verify it works ### Common Mistakes in User Stories - Too vague: "As a user, I want the product to be faster" — what specifically should be faster? - Solution-prescriptive: "As a user, I want a dropdown menu" — describe the need, not the UI widget - No benefit: "As a user, I want to click a button" — why? What does it accomplish? - Too large: "As a user, I want to manage my team" — break this into specific capabilities - Internal focus: "As the engineering team, we want to refactor the database" — this is a task, not a user story ## Requirements Categorization ### MoSCoW Framework - **Must have**: Without these, the feature is not viable. Non-negotiable. - **Should have**: Important but not critical for launch. High-priority fast follows. - **Could have**: Desirable if time permits. Will not delay delivery if cut. - **Won't have (this time)**: Explicitly out of scope. May revisit in future versions. ### Tips for Categorization - Be ruthless about P0s. The tighter the must-have list, the faster you ship and learn. - If everything is P0, nothing is P0. Challenge every must-have: "Would we really not ship without this?" - P1s should be things you are confident you will build soon, not a wish list. - P2s are architectural insurance — they guide design decisions even though you are not building them now. ## Success Metrics Definition ### Leading Indicators Metrics that change quickly after launch (days to weeks): - **Adoption rate**: % of eligible users who try the feature - **Activation rate**: % of users who complete the core action - **Task completion rate**: % of users who successfully accomplish their goal - **Time to complete**: How long the core workflow takes - **Error rate**: How often users encounter errors or dead ends - **Feature usage frequency**: How often users return to use the feature ### Lagging Indicators Metrics that take time to develop (weeks to months): - **Retention impact**: Does this feature improve user retention? - **Revenue impact**: Does this drive upgrades, expansion, or new revenue? - **NPS / satisfaction change**: Does this improve how users feel about the product? - **Support ticket reduction**: Does this reduce support load? - **Competitive win rate**: Does this help win more deals? ### Setting Targets - Targets should be specific: "50% adoption within 30 days" not "high adoption" - Base targets on comparable features, industry benchmarks, or explicit hypotheses - Set a "success" threshold and a "stretch" target - Define the measurement method: what tool, what query, what time window - Specify when you will evaluate: 1 week, 1 month, 1 quarter post-launch ## Acceptance Criteria Write acceptance criteria in Given/When/Then format or as a checklist: **Given/When/Then**: - Given [precondition or context] - When [action the user takes] - Then [expected outcome] Example: - Given the admin has configured SSO for their organization - When a team member visits the login page - Then they are automatically redirected to the organization's SSO provider **Checklist format**: - [ ] Admin can enter SSO provider URL in organization settings - [ ] Team members see "Log in with SSO" button on login page - [ ] SSO login creates a new account if one does not exist - [ ] SSO login links to existing account if email matches - [ ] Failed SSO attempts show a clear error message ### Tips for Acceptance Criteria - Cover the happy path, error cases, and edge cases - Be specific about the expected behavior, not the implementation - Include what should NOT happen (negative test cases) - Each criterion should be independently testable - Avoid ambiguous words: "fast", "user-friendly", "intuitive" — define what these mean concretely ## Scope Management ### Recognizing Scope Creep Scope creep happens when: - Requirements keep getting added after the spec is approved - "Small" additions accumulate into a significantly larger project - The team is building features no user asked for ("while we're at it...") - The launch date keeps moving without explicit re-scoping - Stakeholders add requirements without removing anything ### Preventing Scope Creep - Write explicit non-goals in every spec - Require that any scope addition comes with a scope removal or timeline extension - Separate "v1" from "v2" clearly in the spec - Review the spec against the original problem statement — does everything serve it? - Time-box investigations: "If we cannot figure out X in 2 days, we cut it" - Create a "parking lot" for good ideas that are not in scope ## Output Format Use markdown with clear headers. Keep the document scannable — busy stakeholders should be able to read just the headers and bold text to get the gist. ## Tips - Be opinionated about scope. It is better to have a tight, well-defined spec than an expansive vague one. - If the user's idea is too big for one spec, suggest breaking it into phases and spec the first phase. - Success metrics should be specific and measurable, not vague ("improve user experience"). - Non-goals are as important as goals. They prevent scope creep during implementation. - Open questions should be genuinely open — do not include questions you can answer from context. --- Attribution added by YourAIKit. It is not part of the upstream file. - Source: https://github.com/anthropics/knowledge-work-plugins/tree/main/product-management/skills/write-spec - Credit: Anthropic, Knowledge Work Plugins (product-management) - Upstream copy: anthropics/knowledge-work-plugins at commit 33d3dea41a341b341d4f5da2e8801ae0c89be2b8, product-management/skills/write-spec/SKILL.md - Copyright: held by the upstream authors credited above - License: Apache-2.0. Full text: https://youraikit.com/licenses/anthropics-knowledge-work-plugins-product-management/LICENSE - The full upstream license text (LICENSE) follows. License (LICENSE): ```text Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 1. Definitions. "License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document. "Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License. "Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity. "You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License. "Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files. "Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types. "Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below). "Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof. "Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution." "Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work. 2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form. 3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed. 4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions: (a) You must give any other recipients of the Work or Derivative Works a copy of this License; and (b) You must cause any modified files to carry prominent notices stating that You changed the files; and (c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and (d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License. You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License. 5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions. 6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file. 7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License. 8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages. 9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability. END OF TERMS AND CONDITIONS APPENDIX: How to apply the Apache License to your work. To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets "[]" replaced with your own identifying information. (Don't include the brackets!) The text should be enclosed in the appropriate comment syntax for the file format. We also recommend that a file or class name and description of purpose be included on the same "printed page" as the copyright notice for easier identification within third-party archives. Copyright [yyyy] [name of copyright owner] Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ```