Table of Contents

• When to Use
• Integration
• Specification Structure
• 1. Overview Section
• 2. Functional Requirements (FR-XXX)
• FR-001: [Requirement Name]
• 3. Non-Functional Requirements (NFR-XXX)
• NFR-001: [Category] - [Requirement]
• 4. Technical Constraints
• 5. Out of Scope
• Out of Scope (v1.0)
• Clarification Workflow
• Ambiguity Detection
• Question Generation
• Clarification Session
• Quality Checks
• Output Format
• Change History
• Overview
• Functional Requirements
• Non-Functional Requirements
• Technical Constraints
• Out of Scope
• Dependencies
• Acceptance Testing Strategy
• Success Criteria
• Glossary
• References
• Acceptance Criteria Patterns
• Given-When-Then
• Error Cases
• Performance Criteria
• Security Criteria
• Related Skills
• Related Commands
• Examples

Project Specification Skill

When To Use

• After brainstorming phase completes
• Have project brief but need detailed requirements
• Need testable acceptance criteria for implementation
• Planning validation and testing strategy
• Translating business requirements into technical specs
• Defining scope boundaries and out-of-scope items

When NOT To Use

• Still exploring problem space (use

  Skill(attune:project-brainstorming)

  instead)
• Already have detailed specification (use

  Skill(attune:project-planning)

  instead)
• Refining existing implementation (use code review skills)
• Making strategic decisions (use

  Skill(attune:war-room)

  for complex choices)

Integration

• Delegates to

  Skill(spec-kit:spec-writing)

  for methodology
• Uses spec-kit templates and validation
• Enables clarification workflow

• Standalone specification framework
• Requirement templates
• Acceptance criteria patterns

Specification Structure

1. Overview Section

• Purpose: What the project achieves (1-2 sentences)
• Scope: IN/OUT boundaries
• Stakeholders: Who cares and why

2. Functional Requirements (FR-XXX)

### FR-001: [Requirement Name]

**Description**: Clear, unambiguous description

**Acceptance Criteria**:
- [ ] Given [context], when [action], then [expected result]
- [ ] Given [context], when [action], then [expected result]

**Priority**: High | Medium | Low
**Dependencies**: FR-002, FR-005
**Estimated Effort**: S | M | L | XL

--help

• Description has no ambiguous words (might, could, maybe, probably)
• At least 2 acceptance criteria (happy path + error case)
• Criteria use Given-When-Then format
• Criteria are testable (observable outcomes)
• Dependencies are explicit

3. Non-Functional Requirements (NFR-XXX)

• Performance: Response times, throughput, resource limits
• Security: Authentication, authorization, data protection, compliance
• Reliability: Uptime, error handling, recovery, fault tolerance
• Usability: UX requirements, accessibility, documentation
• Maintainability: Code quality, testing, observability

### NFR-001: [Category] - [Requirement]

**Requirement**: [Specific, measurable requirement]

**Measurement**: [How to verify]
- Metric: [What to measure]
- Target: [Specific threshold]
- Tool: [How to measure]

**Priority**: Critical | High | Medium | Low

--help

4. Technical Constraints

• Technology stack selections with rationale
• Integration requirements
• Data requirements (schema, migrations)
• Deployment constraints
• Regulatory/compliance requirements

5. Out of Scope

## Out of Scope (v1.0)

- [Feature explicitly NOT included]
- [Capability deferred to later version]
- [Integration not planned]

**Rationale**: [Why these are excluded]

--help

Clarification Workflow

Ambiguity Detection

• Vague quantifiers (many, few, several, most)
• Ambiguous terms (user-friendly, fast, scalable)
• Missing dependencies
• Untestable criteria
• Conflicting requirements

Question Generation

**Question [N]**: [Reference to FR/NFR]

**Ambiguity**: [What is unclear]

**Impact**: [Why this matters]

**Options**:
- Option A: [Interpretation 1]
- Option B: [Interpretation 2]

**Recommendation**: [Preferred option with rationale]

--help

Clarification Session

1. Present all questions
2. Gather stakeholder responses
3. Update specification
4. Re-validate for new ambiguities
5. Iterate until clear

Quality Checks

• ✅ All requirements have unique IDs (FR-XXX, NFR-XXX)
• ✅ All functional requirements have ≥2 acceptance criteria
• ✅ All criteria use Given-When-Then format
• ✅ No ambiguous language detected
• ✅ Dependencies documented
• ✅ Effort estimates provided
• ✅ Out of scope explicitly stated
• ✅ Success criteria defined

Output Format

docs/specification.md

# [Project Name] - Specification v[version]

**Author**: [Name]
**Date**: [YYYY-MM-DD]
**Status**: Draft | Review | Approved | Implemented

## Change History

| Version | Date | Author | Changes |
|---------|------|--------|---------|
| 0.1.0 | 2026-01-02 | Alex | Initial draft |

## Overview

**Purpose**: [1-2 sentence purpose]

**Scope**:
- **IN**: [What's included]
- **OUT**: [What's excluded]

**Stakeholders**:
- [Stakeholder 1]: [Their interest]
- [Stakeholder 2]: [Their interest]

## Functional Requirements

[FR-XXX sections]

## Non-Functional Requirements

[NFR-XXX sections]

## Technical Constraints

[Technology, integration, data, deployment]

## Out of Scope

[Explicit exclusions with rationale]

## Dependencies

[External dependencies, third-party services]

## Acceptance Testing Strategy

[How requirements will be validated]

## Success Criteria

- [ ] [Measurable success indicator 1]
- [ ] [Measurable success indicator 2]

## Glossary

[Domain terms and definitions]

## References

[Related documents, research, prior art]

pytest -v

Acceptance Criteria Patterns

Given-When-Then

Given [initial context/state]
When [action occurs]
Then [expected outcome]

--help

• Given unauthenticated user, when accessing dashboard, then redirect to login
• Given valid credentials, when logging in, then create session and redirect to dashboard
• Given expired session, when making API request, then return 401 Unauthorized

Error Cases

• Invalid input handling
• Authentication/authorization failures
• Network/service failures
• Resource exhaustion
• Edge cases and boundaries

Performance Criteria

• "Dashboard loads in < 2 seconds" (measurable)
• NOT "Dashboard is fast" (vague)

Security Criteria

• "All API endpoints require authentication" (testable)
• NOT "System is secure" (vague)

Related Skills

• Skill(spec-kit:spec-writing)

  - Spec-kit methodology (if available)

• Skill(attune:project-brainstorming)

  - Previous phase

• Skill(attune:project-planning)

  - Next phase

Related Commands

• /attune:specify

  - Invoke this skill

• /attune:specify --clarify

  - Run clarification workflow

• /attune:blueprint

  - Next step in workflow

Examples

/attune:specify

Troubleshooting

Common Issues

--verbose