micsapp 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
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:
### 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:
### 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:
## 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:
**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:
- Present all questions
- Gather stakeholder responses
- Update specification
- Re-validate for new ambiguities
- 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:
# [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
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:
- Verify
docs/specification.mdexists and is non-empty - Display checkpoint message to user:
Specification complete. Saved to docs/specification.md. Proceeding to planning phase... - Invoke next phase:
Skill(attune:project-planning)
Bypass Conditions (ONLY skip continuation if ANY true):
--standaloneflag was provided by the userdocs/specification.mddoes 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 phaseSkill(attune:project-planning)- AUTO-INVOKED next phase after specificationSkill(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