Agent Skills: Specification Writing Skill

Specification Writing Skill

This skill defines how to write specifications that follow the project's conventions. CRITICAL: Stick to the Domain Specific Language in this document. Do not add your own extra keys or structure.

Before Writing a Spec

CRITICAL — before adding any requirements:

1. Check for conflicting specs — read any existing spec.yaml in the same feature area to avoid overlap
2. Check for duplicated requirements — if a requirement already exists in another spec (even worded differently), do not restate it
3. Update the existing spec first if one already covers this feature

Requirement ID uniqueness is enforced by a linter — see scripts/check-spec-ids.sh.

Specification Location

Specifications live close to the code following the principle of locality of behavior:

• Spec filename: spec.yaml
• Location: In the same directory as the code it specifies, or in a feature-specific subdirectory
• Example: src/feature/spec.yaml

Specification Format

Every spec.yaml file must follow this YAML structure:

feature:
  name: Brief Feature Title
  user: user role
  goal: goal/capability
  solutions:
    - Solution 1
    - Solution 2

requirements:
  - id: REQ-XXX-001
    test: to-implement
    code: to-implement
    description: Specific, testable requirement
  - id: REQ-XXX-002
    test: to-implement
    code: to-implement
    description: Another specific requirement

Feature Section

The feature section captures the user story and possible solutions.

• name: Brief title for the feature
• user: The end user role (always from the user's perspective, never a system component)
• goal: The goal or capability (what they want)
• solutions: List of possible implementation approaches

Rationale for User Goals + Possible Solutions:

• Focus on WHAT the user wants to achieve, not a specific HOW
• Acknowledge that multiple solutions may exist to meet the user's goal
• Solutions should be considered throughout implementation
• Design the codebase to be modular enough to swap solutions without major refactoring
• Keeps options open until implementation details are needed

Requirements Section

Status markers for test field:

• to-implement = not yet implemented
• unit = implemented via unit test
• acceptance = implemented via acceptance test
• wont-implement = intentionally not tested

Status markers for code field:

• to-implement = not yet implemented
• done = implemented
• wont-implement = intentionally not implemented

Requirements are a flat list — do NOT nest or group them. Grouping by category creates artificial structure that encourages duplication and makes it harder to maintain sequential numbering.

Requirement naming:

• Use feature-specific prefix for the id
• Number sequentially starting from 001
• Sequentiality does not need to be enforced (reduce work renumbering)
  • You can skip numbers if a requirement is removed
  • Add characters if adding a requirement between other requirements
• Keep requirements atomic and testable
• One requirement per list item

CRITICAL - Atomic Requirements:

• Each requirement must test ONE specific thing
• If a requirement has "and" or lists multiple attributes, split it into separate requirements
• Each requirement should map to one test (or a small set of closely related tests)

CRITICAL - User-Facing Requirements Only:

• Requirements must describe FEATURES from the user's perspective
• Each requirement should be stated ONLY ONCE in the spec
• DO NOT create separate requirements for implementation details

CRITICAL - No Implementation Details in Requirements:

• Requirements must describe WHAT the system does, never HOW it does it
• DO NOT name specific libraries, frameworks, or tools in requirements
• Library/tool choices belong in the solutions list, not in requirements
• A requirement should remain valid even if the underlying implementation is swapped

CRITICAL - Do Not Duplicate Existing Functionality:

• Before writing any requirement, check whether the behavior is already implemented and tested in an existing module
• If the feature reuses existing infrastructure do NOT add requirements for that infrastructure
• Only specify behavior that is NEW to this feature

Before adding a requirement, ask:

1. Is this something the user directly experiences or cares about?
2. Have I already stated this requirement elsewhere in the spec or in another spec file?
3. Is this describing WHAT the system does for the user, or HOW it does it internally?
4. Is this behavior already implemented and tested in an existing module that this feature will reuse?

Scenarios Section (Optional)

Use the acceptance-test skill for writing scenarios and acceptance tests.

Scenarios are only needed when the feature requires end-to-end testing across multiple modules. Ask the user if scenarios apply before adding them.

Integration with STDD Workflow

This spec skill is STEP 1 of the spec-test-driven development workflow:

1. Write Spec ← (this skill)
2. Write Tests (based on spec requirements)
3. Implement Code (to pass tests)

After completing the spec:

1. Get user approval
2. Proceed to writing tests based on requirements using TDD
3. Follow stdd skill for remaining steps