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.

OpenClaw / Moltbot / Clawbot

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/.
• # 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: CriterionMeaningTest QuestionIndependentNo ordering dependency on othersCan this be built and released alone?NegotiableDetails can be discussedIs this a conversation starter, not a contract?ValuableDelivers value to the personaWould the persona care about this?EstimableTeam can estimate effortIs the scope clear enough to size?SmallFits in a single iterationCan this ship in one sprint?TestableClear pass/fail verificationCan QA write a test for this?

Good vs Bad User Stories

BadWhy It's BadGood"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"

Pattern 1: Happy Path

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

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

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

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

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: PriorityLabelDefinitionPersona AlignmentP0MustProduct is unusable without thisBlocks the persona's primary goalP1ShouldSignificant value, painful to deferAddresses a top-3 pain pointP2CouldNice to have, enhances experienceImproves a secondary journeyP3Won'tExplicitly deferred (this release)Low-frequency need or niche scenario Prioritization process: List all candidate features Map each to a persona pain point or journey step Assign MoSCoW based on persona impact, not technical interest Validate: Do all P0s together form a usable product for the target persona? Cut scope until P0s are achievable in the timeline

Specification Anti-Patterns

Anti-PatternExampleFixVague requirement"System should be user-friendly"Define measurable criteria: "Task completion in < 3 clicks"Missing edge casesOnly specifying the happy pathAdd boundary, error, and concurrent-use scenariosNo acceptance criteria"Implement search"Add Given/When/Then for each scenarioSolution 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 exportUnbounded scope"Support all file formats"List exact formats: "PDF, CSV, XLSX"Implicit assumptionsAssuming auth exists without stating itList all dependencies explicitly

Integration with Workflow

Feature specs connect to the broader development process: Persona docs (docs/PERSONA.md) — Source of truth for user needs Feature specs (docs/specs/) — This skill's output; the development contract Task creation — Each spec becomes one or more development tasks Implementation — Developers reference the spec for scope and criteria Testing — QA derives test cases directly from acceptance criteria 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

NEVER write a spec without referencing a persona — every feature exists for a user NEVER skip acceptance criteria — "obvious" requirements cause the most bugs NEVER use vague qualifiers as requirements — "fast", "easy", "intuitive" are not testable NEVER combine multiple features in one spec — one spec, one feature, one clear scope NEVER specify implementation details in user stories — describe the what, not the how NEVER mark a spec as Approved without edge cases documented — happy paths are the easy part NEVER assume dependencies are obvious — list every system, API, feature, and data source the spec relies on