writing-specs

jkappers 的头像作者 jkappers

创建捕获需求和验收标准的功能规范。在编写规范、记录功能或定义需求时使用。

📖 中文导读:创建捕获需求和验收标准的功能规范。在编写规范、记录功能或定义需求时使用。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

name: writing-specs description: Creates feature specifications capturing requirements and acceptance criteria. Use when writing specs, documenting features, or defining requirements.

Spec Writing

Create specifications capturing WHAT and WHY. Do not include implementation details (those belong in technical-details.md).

Required Sections

  1. Feature Overview (2-3 paragraphs) - What it does, who uses it, what problem it solves

  2. Success Criteria - Measurable outcomes defining "done"

  3. Design Goals - Primary (must achieve) and secondary (nice to have)

  4. User Experience (1-2 paragraphs) - How users interact, expected journey

  5. Design Rationale (1-2 paragraphs) - Why this approach, key trade-offs

  6. Constraints and Assumptions - Technical constraints, business assumptions

  7. Functional Requirements (FR-N format) - Max 6-8 per spec, each specific and testable, with Given-When-Then acceptance criteria

  8. Edge Cases and Error Handling - Unusual inputs, failure scenarios, expected behaviors

Acceptance Criteria Format

- [ ] Given [context], when [action], then [expected result]

Include 2-4 criteria per requirement covering happy path and key failure cases.

Exclusions

Do not include: architecture diagrams, code examples, database schemas, API signatures, development estimates, timeline references, or phase sections.

Validation

Before completing:

  • Single MVP focus (one deliverable)
  • All requirements have testable criteria
  • No TODO/TBD placeholders
  • Edge cases documented

Scope Check

If more than 6-8 requirements, the feature is too large. Identify 3-4 core requirements and flag the rest for a separate spec. Document in a "Scope Notes" section.

Directory Structure

specs/
├── YYYY-MM-DD-feature-name/
│   ├── README.md              # Spec (WHAT and WHY)
│   └── technical-details.md   # Implementation (HOW)
└── historical/

Templates

  • templates/spec-readme.md - New spec template
  • references/spec-guide.md - Guidelines and examples