feature-specification

# Feature Specification (Meta-Skill) Bridge persona documentation and development. This skill translates user needs, pain points, and journeys identified in persona docs into structured, implementable feature specifications with clear acceptance criteria. ## Installation ### OpenClaw / Moltbot / Clawbot ```bash npx clawhub@latest install feature-specification ``` --- ## Purpose Persona docs define *who* and *why*. Feature specs define *what* and *how well*. This skill closes the gap: - Extracts actionable features from persona pain points and journeys - Structures requirements so developers know exactly what to build - Defines acceptance criteria so QA knows exactly what to verify - Prevents scope ambiguity before a single line of code is written --- ## When to Use - After persona docs exist (`docs/PERSONA.md` or `docs/personas/`) - Before development begins on a new feature or product - When a feature request lacks clear acceptance criteria - When stakeholders disagree on what "done" means - When converting user feedback into development work --- ## Feature Spec Template Use this structure for every feature specification. Place specs in `docs/specs/` or `docs/features/`. ```markdown # Feature: [Feature Name] ## Metadata - **Priority:** [Must / Should / Could / Won't] - **Target Persona:** [Persona name from persona docs] - **Status:** Draft | Review | Approved | In Progress | Complete - **Estimated Effort:** [T-shirt size: XS / S / M / L / XL] ## Problem Statement [Directly reference the persona pain point this feature addresses. Quote or link to the relevant section of persona docs.] ## Solution Description [High-level description of what the feature does and how it solves the problem. 2-4 sentences. No implementation details.] ## User Stories - As a [persona], I want [action], so that [benefit]. - As a [persona], I want [action], so that [benefit]. ## Acceptance Criteria ### Scenario: [Happy path description] - **Given** [precondition] - **When** [action] - **Then** [expected result] ### Scenario: [Alternative path description] - **Given** [precondition] - **When** [action] - **Then** [expected result] ### Scenario: [Error case description] - **Given** [precondition] - **When** [invalid action] - **Then** [error handling result] ## Edge Cases - [ ] [Edge case 1 — description and expected behavior] - [ ] [Edge case 2 — description and expected behavior] ## Non-Functional Requirements - **Performance:** [Response time, throughput, load targets] - **Accessibility:** [WCAG level, keyboard nav, screen reader support] - **Security:** [Auth requirements, data sensitivity, input validation] - **Browser/Device:** [Support matrix] ## Dependencies - [Feature or system this depends on] - [External API or service required] ## Out of Scope - [Explicitly list what this feature does NOT include] - [Prevents scope creep during development] ## Design References - [Link to mockups, wireframes, or design system components] - [Screenshots or diagrams if available] ``` --- ## Writing Effective User Stories User stories connect persona needs to developer tasks. Apply the INVEST criteria: | Criterion | Meaning | Test Question | |-----------|--------------------------------------|-------------------------------------------| | Independent | No ordering dependency on others | Can this be built and released alone? | | Negotiable | Details can be discussed | Is this a conversation starter, not a contract? | | Valuable | Delivers value to the persona | Would the persona care about this? | | Estimable | Team can estimate effort | Is the scope clear enough to size? | | Small | Fits in a single iteration | Can this ship in one sprint? | | Testable | Clear pass/fail verification | Can QA write a test for this? | ### Good vs Bad User Stories | Bad | Why It's Bad | Good | |-----|-------------|------| | "Users can log in" | No persona, no benefit | "As a returning customer, I want to log in with my email, so that I can access my order history" | | "Make it fast" | Vague, untestable | "As a mobile user on 3G, I want the product list to load in under 2s, so that I don't abandon the page" | | "Add admin panel" | Solution-first, no problem | "As a store manager, I want to update product prices without developer help, so that I can respond to market changes daily" | | "Handle errors" | No specificity | "As a checkout user, I want clear feedback when my payment fails, so that I know whether to retry or use a different card" | | "Implement caching" | Implementation detail, not a story | "As a repeat visitor, I want previously viewed pages to load instantly, so that browsing feels responsive" | --- ## Acceptance Criteria Patterns ### Pattern 1: Happy Path ```gherkin Given a logged-in customer with items in their cart When they click "Checkout" Then they are taken to the payment page with their cart summary visible ``` ### Pattern 2: Boundary Conditions ```gherkin Given a cart with 100 items (maximum allowed) When the user tries to add another item Then they see "Cart limit reached — remove an item to add a new one" And the item is NOT added to the cart ``` ### Pattern 3: Error Cases ```gherkin Given a user submitting the registration form When the email field contains "not-an-email" Then the form shows inline validation: "Enter a valid email address" And the form is NOT submitted And focus moves to the email field ``` ### Pattern 4: State Transitions ```gherkin Given an order with status "Processing" When the warehouse marks it as shipped Then the order status changes to "Shipped" And the customer receives a shipping confirmation email within 5 minutes And the tracking number is visible on the order detail page ``` ### Pattern 5: Negative / Security ```gherkin Given a user who is NOT the account owner When they attempt to access /account/settings via direct URL Then they receive a 403 Forbidden response And the access attempt is logged ``` --- ## Priority Framework Apply MoSCoW prioritization, anchored to persona impact: | Priority | Label | Definition | Persona Alignment | |----------|---------|-----------------------------------------------|------------------------------------------| | P0 | Must | Product is unusable without this | Blocks the persona's primary goal | | P1 | Should | Significant value, painful to defer | Addresses a top-3 pain point | | P2 | Could | Nice to have, enhances experience | Improves a secondary journey | | P3 | Won't | Explicitly deferred (this release) | Low-frequency need or niche scenario | **Prioritization process:** 1. List all candidate features 2. Map each to a persona pain point or journey step 3. Assign MoSCoW based on persona impact, not technical interest 4. Validate: Do all P0s together form a usable product for the target persona? 5. Cut scope until P0s are achievable in the timeline --- ## Specification Anti-Patterns | Anti-Pattern | Example | Fix | |-------------------------------|------------------------------------------|--------------------------------------------------| | Vague requirement | "System should be user-friendly" | Define measurable criteria: "Task completion in < 3 clicks" | | Missing edge cases | Only specifying the happy path | Add boundary, error, and concurrent-use scenarios | | No acceptance criteria | "Implement search" | Add Given/When/Then for each scenario | | Solution masquerading as need | "Use Redis for caching" | State the need: "Repeat queries return in < 50ms" | | Missing personas | "Users can export data" | Specify which persona and why they export | | Unbounded scope | "Support all file formats" | List exact formats: "PDF, CSV, XLSX" | | Implicit assumptions | Assuming auth exists without stating it | List all dependencies explicitly | --- ## Integration with Workflow Feature specs connect to the broader development process: 1. **Persona docs** (`docs/PERSONA.md`) — Source of truth for user needs 2. **Feature specs** (`docs/specs/`) — This skill's output; the development contract 3. **Task creation** — Each spec becomes one or more development tasks 4. **Implementation** — Developers reference the spec for scope and criteria 5. **Testing** — QA derives test cases directly from acceptance criteria 6. **Review** — PR reviews check that acceptance criteria are met When using with the `/new-feature` command or similar workflows: - Read the relevant persona doc first - Generate the spec using this template - Validate acceptance criteria cover happy path, errors, and edge cases - Confirm priority with stakeholders before development begins --- ## NEVER Do 1. **NEVER write a spec without referencing a persona** — every feature exists for a user 2. **NEVER skip acceptance criteria** — "obvious" requirements cause the most bugs 3. **NEVER use vague qualifiers as requirements** — "fast", "easy", "intuitive" are not testable 4. **NEVER combine multiple features in one spec** — one spec, one feature, one clear scope 5. **NEVER specify implementation details in user stories** — describe the *what*, not the *how* 6. **NEVER mark a spec as Approved without edge cases documented** — happy paths are the easy part 7. **NEVER assume dependencies are obvious** — list every system, API, feature, and data source the spec relies on