@athola/project-specification

---
name: project-specification
description: "Transform project briefs into testable specifications with acceptance criteria. Use for requirements translation, spec creation, pre-implementation. Skip if spec exists or still exploring."
# Custom metadata (not used by Claude for matching):
model_preference: claude-sonnet-4
category: workflow
tags: [specification, requirements, acceptance-criteria, spec-driven-development]
complexity: intermediate
estimated_tokens: 2200
---
## Table of Contents

- [When to Use](#when-to-use)
- [Integration](#integration)
- [Specification Structure](#specification-structure)
- [1. Overview Section](#1-overview-section)
- [2. Functional Requirements (FR-XXX)](#2-functional-requirements-(fr-xxx))
- [FR-001: [Requirement Name]](#fr-001:-[requirement-name])
- [3. Non-Functional Requirements (NFR-XXX)](#3-non-functional-requirements-(nfr-xxx))
- [NFR-001: [Category] - [Requirement]](#nfr-001:-[category]---[requirement])
- [4. Technical Constraints](#4-technical-constraints)
- [5. Out of Scope](#5-out-of-scope)
- [Out of Scope (v1.0)](#out-of-scope-(v10))
- [Clarification Workflow](#clarification-workflow)
- [Ambiguity Detection](#ambiguity-detection)
- [Question Generation](#question-generation)
- [Clarification Session](#clarification-session)
- [Quality Checks](#quality-checks)
- [Output Format](#output-format)
- [Change History](#change-history)
- [Overview](#overview)
- [Functional Requirements](#functional-requirements)
- [Non-Functional Requirements](#non-functional-requirements)
- [Technical Constraints](#technical-constraints)
- [Out of Scope](#out-of-scope)
- [Dependencies](#dependencies)
- [Acceptance Testing Strategy](#acceptance-testing-strategy)
- [Success Criteria](#success-criteria)
- [Glossary](#glossary)
- [References](#references)
- [Acceptance Criteria Patterns](#acceptance-criteria-patterns)
- [Given-When-Then](#given-when-then)
- [Error Cases](#error-cases)
- [Performance Criteria](#performance-criteria)
- [Security Criteria](#security-criteria)
- [Related Skills](#related-skills)
- [Related Commands](#related-commands)
- [Examples](#examples)


# Project Specification Skill

Transform project briefs into structured, testable specifications with acceptance criteria.

## Delegation

For detailed specification writing workflows, this skill delegates to `spec-kit:spec-writing` as the canonical implementation. Use this skill for quick specification needs; use spec-kit for comprehensive specification documents.

## 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

**With spec-kit**:
- Delegates to `Skill(spec-kit:spec-writing)` for methodology
- Uses spec-kit templates and validation
- Enables clarification workflow

**Without spec-kit**:
- 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)

**Format per requirement**:
```markdown
### 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
```
**Verification:** Run the command with `--help` flag to verify availability.

**Validation Rules**:
- 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)

**Categories**:
- **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

**Format**:
```markdown
### 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
```
**Verification:** Run the command with `--help` flag to verify availability.

### 4. Technical Constraints

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

### 5. Out of Scope

**Explicit exclusions** to prevent scope creep:
```markdown
## Out of Scope (v1.0)

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

**Rationale**: [Why these are excluded]
```
**Verification:** Run the command with `--help` flag to verify availability.

## Clarification Workflow

### Ambiguity Detection

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

### Question Generation

For each ambiguity:
```markdown
**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]
```
**Verification:** Run the command with `--help` flag to verify availability.

### Clarification Session

Run interactive Q&A:
1. Present all questions
2. Gather stakeholder responses
3. Update specification
4. Re-validate for new ambiguities
5. Iterate until clear

## Quality Checks

Before completing specification:

- ✅ 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

Save to `docs/specification.md`:

```markdown
# [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]
```
**Verification:** Run `pytest -v` to verify tests pass.

## Acceptance Criteria Patterns

### Given-When-Then

```markdown
Given [initial context/state]
When [action occurs]
Then [expected outcome]
```
**Verification:** Run the command with `--help` flag to verify availability.

**Examples**:
- 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

Always include error scenarios:
- Invalid input handling
- Authentication/authorization failures
- Network/service failures
- Resource exhaustion
- Edge cases and boundaries

### Performance Criteria

Make performance requirements testable:
- "Dashboard loads in < 2 seconds" (measurable)
- NOT "Dashboard is fast" (vague)

### Security Criteria

Make security requirements verifiable:
- "All API endpoints require authentication" (testable)
- NOT "System is secure" (vague)

## Post-Completion: Workflow Continuation (REQUIRED)

**Automatic Trigger**: After Quality Checks pass and `docs/specification.md` is saved, MUST auto-invoke the next phase.

**When continuation is invoked**:
1. Verify `docs/specification.md` exists and is non-empty
2. Display checkpoint message to user:
   ```
   Specification complete. Saved to docs/specification.md.
   Proceeding to planning phase...
   ```
3. Invoke next phase:
   ```
   Skill(attune:project-planning)
   ```

**Bypass Conditions** (ONLY skip continuation if ANY true):
- `--standalone` flag was provided by the user
- `docs/specification.md` does not exist or is empty (phase failed)
- User explicitly requests to stop after specification

**Do NOT prompt the user for confirmation** — this is a lightweight checkpoint, not an interactive gate. The user can always interrupt if needed.

## Related Skills

- `Skill(spec-kit:spec-writing)` - Spec-kit methodology (if available)
- `Skill(attune:project-brainstorming)` - Previous phase
- `Skill(attune:project-planning)` - **AUTO-INVOKED** next phase after specification
- `Skill(attune:mission-orchestrator)` - Full lifecycle orchestration

## Related Commands

- `/attune:specify` - Invoke this skill
- `/attune:specify --clarify` - Run clarification workflow
- `/attune:blueprint` - Next step in workflow

## Examples

See `/attune:specify` command documentation for complete examples.
## Troubleshooting

### Common Issues

**Command not found**
Ensure all dependencies are installed and in PATH

**Permission errors**
Check file permissions and run with appropriate privileges

**Unexpected behavior**
Enable verbose logging with `--verbose` flag