playbooks

home / skills / athola / claude-night-market / spec-writing

spec-writing skill

/plugins/spec-kit/skills/spec-writing

This skill helps you create clear, testable feature specifications with user stories and acceptance criteria focused on user value.

npx playbooks add skill athola/claude-night-market --skill spec-writing

Review the files below or copy the command above to add this skill to your agents.

Files (4)
SKILL.md
3.3 KB
---
name: spec-writing
description: 'Create clear, testable specifications with user stories and acceptance
  criteria.


  spec writing, feature specification, requirements, user stories

  Use when: creating new specifications or writing acceptance criteria

  DO NOT use when: converting specs to tasks - use task-planning.'
category: specification
tags:
- speckit
- specification
- requirements
- user-stories
- acceptance-criteria
dependencies:
- superpowers:brainstorming
tools: []
usage_patterns:
- feature-specification
- requirements-documentation
- user-story-creation
complexity: intermediate
estimated_tokens: 1200
progressive_loading: true
modules:
- success-criteria-patterns
- specification-structure
- checklist-dimensions
---

# Spec Writing

## Overview

Create clear, complete, and testable specifications from natural language feature descriptions. Specifications focus on user value and business needs, avoiding implementation details.

## When To Use

- Creating new feature specifications
- Refining existing specifications
- Writing user stories and acceptance criteria
- Defining success criteria

## When NOT To Use

- Generating implementation tasks - use task-planning

## Core Principles

Focus on user value and business needs rather than implementation details. Avoid specifying technology choices in requirement definitions unless strictly necessary. Ensure every requirement is testable and verifiable with measurable criteria. Limit clarification markers; make informed assumptions based on industry standards and document them explicitly.

## Specification Structure

### Mandatory Sections
1. **Overview/Context**: What problem does this solve?
2. **User Scenarios**: Who uses it and how?
3. **Functional Requirements**: What must it do?
4. **Success Criteria**: How do we know it works?

### Optional Sections
- Non-Functional Requirements (when performance/security critical)
- Edge Cases (when special handling needed)
- Dependencies (when external systems involved)
- Assumptions (when decisions made with incomplete info)

**See**: `modules/specification-structure.md` for detailed templates and guidelines

## Quality Checklist

- [ ] No implementation details present
- [ ] Requirements are testable and unambiguous
- [ ] Success criteria are measurable
- [ ] User scenarios cover primary flows
- [ ] Edge cases identified
- [ ] Scope clearly bounded

## Success Criteria Quick Reference

### Good (User-focused, Measurable, Technology-agnostic)
- "Users complete checkout in under 3 minutes"
- "System supports 10,000 concurrent users"
- "95% of searches return results in under 1 second"

### Bad (Implementation-focused, Internal metrics)
- "API response time under 200ms" -> Use: "Pages load in under 2 seconds"
- "Redis cache hit rate above 80%" -> Use: "Frequently accessed data loads with no noticeable delay"
- "React components render efficiently" -> Use: "UI updates appear with no visible frame drops"

**See**: `modules/success-criteria-patterns.md` for detailed examples and conversion process

## Related Skills

- `speckit-orchestrator`: Workflow coordination
- `task-planning`: Converting specs to tasks
## Troubleshooting

### Common Issues

If specifications are too vague, use the `success-criteria-patterns` module to enforce measurable outcomes. If implementation details leak into specs, review against the "Core Principles" and refactor to focus on user behavior.

Overview

This skill creates clear, complete, and testable feature specifications from natural-language descriptions. It emphasizes user value, measurable success criteria, and avoids implementation details. The outcome is a specification with user scenarios, functional requirements, and verifiable acceptance criteria.

How this skill works

The skill converts feature requests or informal descriptions into a structured specification with an overview/context, user scenarios, functional requirements, and success criteria. It flags required non-functional requirements, edge cases, dependencies, and explicit assumptions when needed. Every requirement is framed to be testable and measurable, and the skill detects and removes implementation-level details.

When to use it

  • Creating new feature specifications from product ideas or stakeholder requests
  • Refining or expanding existing specifications into testable requirements
  • Writing user stories and concrete acceptance criteria for QA
  • Defining measurable success criteria for feature validation
  • Documenting assumptions and dependencies before development planning

Best practices

  • Focus requirements on user value and business outcomes, not internal design
  • Make every acceptance criterion measurable and verifiable
  • Limit technology or implementation specifics unless essential and documented as constraints
  • List primary user scenarios first, then cover important edge cases
  • Record assumptions explicitly when information is incomplete

Example use cases

  • Turn a product manager’s feature brief into a spec with user stories and acceptance tests
  • Refine a vague feature request into clear success criteria and edge-case handling
  • Prepare a specification to hand off to engineering and QA without implementation bias
  • Define success metrics for a launch (e.g., conversion targets, performance thresholds from user perspective)
  • Audit an existing spec to remove implementation details and improve testability

FAQ

Can this skill create development tasks from specs?

No. It focuses on specifications, user stories, and acceptance criteria. Use a separate task-planning process to convert specs into implementation tasks.

How does it handle incomplete information?

It makes reasonable, documented assumptions when necessary and flags areas requiring stakeholder clarification.

Are performance and security requirements included?

Yes, but only when they are relevant to user-facing success criteria or critical system constraints; otherwise they are optional sections to avoid over-specifying.