Use when discovery is complete and the project needs a formal requirements baseline. Transforms discovery output into structured specification artifacts.
Transform discovery insights into a formal specification with detailed requirements and acceptance criteria.
Required: Complete discovery document. If missing, run the oat-project-discover skill first.
OAT MODE: Specification
Purpose: Transform discovery insights into formal, structured requirements with clear acceptance criteria.
When executing this skill, provide lightweight progress feedback so the user can tell what’s happening after they confirm.
Print a phase banner once at start using horizontal separators, e.g.:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ OAT ▸ SPEC ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Before multi-step work, print step indicators, e.g.:
[1/5] Validating discovery + reading context…[2/5] Drafting requirements…[3/5] Refining with user…[4/5] Running quality gate checks…[5/5] Updating state + committing…BLOCKED Activities:
ALLOWED Activities:
Self-Correction Protocol: If you catch yourself:
Recovery:
oat-project-designOAT stores active project context in .oat/config.local.json (activeProject, local-only).
PROJECT_PATH=$(oat config get activeProject 2>/dev/null || true)
PROJECTS_ROOT="${OAT_PROJECTS_ROOT:-$(oat config get projects.root 2>/dev/null || echo ".oat/projects/shared")}"
PROJECTS_ROOT="${PROJECTS_ROOT%/}"
If PROJECT_PATH is missing/invalid:
{project-name}PROJECT_PATH to ${PROJECTS_ROOT}/{project-name}mkdir -p .oat
oat config set activeProject "$PROJECT_PATH"
If PROJECT_PATH is valid: derive {project-name} as the directory name (basename of the path).
cat "$PROJECT_PATH/discovery.md" | head -10 | grep "oat_status:"
Required frontmatter:
oat_status: completeoat_ready_for: oat-project-specIf not complete: Block and ask user to finish discovery first.
Read "$PROJECT_PATH/discovery.md" completely to understand:
Minimum viable requirements check:
Verify discovery includes:
If any missing:
oat-project-discover to completeWhy: Prevents "formalized vagueness" - a spec is only as good as the discovery it's based on.
Read for context:
.oat/repo/knowledge/project-index.md.oat/repo/knowledge/architecture.md.oat/repo/knowledge/integrations.md (for dependencies).oat/repo/knowledge/concerns.md (for constraints)Copy template: .oat/templates/spec.md → "$PROJECT_PATH/spec.md"
Update frontmatter:
---
oat_status: in_progress
oat_ready_for: null
oat_blockers: []
oat_last_updated: { today }
---
Transform from discovery:
Write 2-4 paragraphs clearly describing the problem being solved.
Primary Goals: Must-have outcomes (from Key Decisions + Success Criteria) Secondary Goals: Nice-to-have outcomes (from Success Criteria marked as optional)
Use clear, measurable language.
Copy from discovery "Out of Scope" section, adding:
Transform Key Decisions and Success Criteria into structured requirements.
Functional Requirements (FR):
**FR1: {Requirement Name}**
- **Description:** {What the system must do}
- **Acceptance Criteria:**
- {Testable criterion 1}
- {Testable criterion 2}
- **Priority:** P0 / P1 / P2
Non-Functional Requirements (NFR):
**NFR1: {Requirement Name}**
- **Description:** {Performance, security, usability requirement}
- **Acceptance Criteria:**
- {Measurable criterion}
- **Priority:** P0 / P1 / P2
Priorities:
Start with draft requirements, then iterate with user in Step 10.
Iterative process:
oat_last_updated: {today}Focus areas:
Copy from discovery "Constraints" section, adding:
From knowledge base and discovery:
Transform "Options Considered" into design proposal:
## High-Level Design (Proposed)
{2-3 paragraph overview of chosen approach}
**Key Components:**
- {Component 1} - {Brief description}
- {Component 2} - {Brief description}
**Alternatives Considered:**
- {Alternative 1} - {Why rejected}
- {Alternative 2} - {Why rejected}
**Open Questions:**
- {Question needing resolution}
Keep high-level - detailed design comes in next phase.
Guardrail: Do not name specific scripts/files/functions here. Describe components and responsibilities only.
Transform "Success Criteria" into measurable metrics:
Create traceability matrix in spec.md "Requirement Index" section:
For each requirement (FR and NFR):
| Column | Content |
|---|---|
| ID | FR1, FR2, NFR1, etc. (sequential) |
| Description | Brief 1-sentence summary |
| Priority | P0/P1/P2 from requirement |
| Verification | method: pointer — how this will be verified |
| Planned Tasks | Leave as "TBD - see plan.md" |
Verification column format: method: pointer
unit — isolated unit testsintegration — tests spanning components/servicese2e — end-to-end user flow testsmanual — human verification requiredperf — performance/load testingunit: auth token validation, e2e: login flow, perf: API latencysee acceptance criteria (too vague)Why this matters:
oat-project-plan in breaking down work systematicallyBefore marking complete, run through this quality checklist:
Completeness Check:
Quality Check:
Boundary Check:
If any checks fail:
oat_last_updated: {today}If all checks pass:
Read "$PROJECT_PATH/state.md" frontmatter:
oat_hill_checkpointsoat_hill_completedIf "spec" is in oat_hill_checkpoints, require explicit user approval before advancing.
Approval prompt (required):
oat-project-design?"Optional independent review path:
oat-project-review-provide artifact specIf user does not approve yet:
oat_status: in_progressoat_ready_for: null"spec" to oat_hill_completed.If spec is not configured as a HiLL checkpoint, or user explicitly approves, continue to Step 18.
Update frontmatter:
---
oat_status: complete
oat_ready_for: oat-project-design
oat_blockers: []
oat_last_updated: { today }
---
Update "$PROJECT_PATH/state.md":
Frontmatter updates:
oat_current_task: nulloat_last_commit: {commit_sha_from_step_20}oat_blockers: []oat_phase: specoat_phase_status: completeoat_project_state_updated: "{ISO 8601 UTC timestamp}""spec" is in oat_hill_checkpoints: append "spec" to oat_hill_completed arrayNote: Only append to oat_hill_completed when the phase is configured as a HiLL gate.
Update content:
## Current Phase
Specification - Ready for design phase
## Progress
- ✓ Discovery complete
- ✓ Specification complete
- ⧗ Awaiting design phase
Note: This shows what users will do when USING oat-project-spec. During implementation of OAT itself, use standard commit format.
git add "$PROJECT_PATH/"
git commit -m "docs: complete specification for {project-name}
Requirements:
- {N} functional requirements (P0: {n}, P1: {n}, P2: {n})
- {N} non-functional requirements (P0: {n}, P1: {n}, P2: {n})
Ready for design phase"
Specification phase complete for {project-name}.
Created:
- {N} functional requirements
- {N} non-functional requirements
- High-level design approach
- Success metrics
Next: Create detailed design with the oat-project-design skill