| name | specification-writing |
| description | Authoritative source for all specification document generation workflows (Epics, Feature PRDs, Tasks). Provides standardized templates, procedures, and naming conventions for consistent documentation across all projects. |
| version | 2.0.0 |
| inputs | [{"parent_spec_path":"absolute path to parent spec (epic for feature, feature for task)"},{"current_scope_path":"absolute path to current scope document (optional)"},{"related_research_path":"absolute path to related research findings (optional)"},{"design_docs_paths":"list of design document paths (optional)"},{"previous_spec_path":"absolute path to a previous version for comparison (optional)"}] |
| outputs | [{"selected_workflow":"one of {decompose-epic, write-epic, write-feature-prd, write-task, plan-epic-ba-plan, plan-epic-tech-plan, plan-feature-ba-plan, plan-feature-tech-plan, check-ba-docs, check-tech-docs, refine-task-requirements}"},{"specification_document":"created or updated specification markdown"},{"acceptance_criteria":"structured list of acceptance criteria"},{"dependencies":"identified dependencies on other epics/features/tasks"},{"decomposition":"if applicable, child features/tasks decomposed from the spec"},{"tech_plan":"detailed implementation planning (if applicable)"}] |
Specification Writing Skill
This skill provides technical product management and specification writing capabilities with standardized workflows and templates for creating three types of specification documents:
- Epic PRDs — High-level product requirements for major initiatives
- Feature PRDs — Detailed requirements for individual features within epics
- Implementation Tasks — Agent-executable work items that implement features
Suggested Upstream Input
An epic or feature PRD entering this skill should typically be grounded in upstream discovery/design artifacts (vision, success criteria, personas, journey maps, friction findings, validation verdicts). When such artifacts exist, every spec produced here should cite them so the SDLC inherits the validated scope and success bar.
If upstream artifacts are missing, suggest the user produce them first — but do not block. Some initiatives (small fixes, internal tooling, mid-stream pivots) legitimately enter the SDLC without a full discovery trail, and the user is the one who decides whether the upstream artifacts are needed for this piece of work.
Feature-Level Sequence
The canonical SDLC feature sequence is:
feature.md (PRD) → wireframes.md → [prototype.md — optional] → architecture (02-…07-) → tasks → build
- Feature PRD is produced by
write-feature-prd.md in this skill (business-analyst). User stories live as a section inside this file.
- Wireframes and prototype are produced by the
feature-design skill (ux-designer, with cx-designer reviewing). Invoked after the PRD is approved and before architecture/tasks so wireframes shape downstream design.
- Tasks are produced by
write-task.md (business-analyst). They MUST cite the wireframes (and prototype if present) by canonical path in their Design References sections — see context/task-template.md.
If a feature touches frontend code and wireframes are missing, write-task.md will stop and recommend running the feature-design workflow first.
Workflow Selection
Based on what the user needs, invoke the appropriate workflow:
Task-Level Refinement
When: A task needs BA or technical refinement.
Invoke: workflows/refine-task-requirements.md
Output: Updated PRD sections or design docs for the task.
Epic Creation
When: User wants to document a new epic or major initiative.
Invoke: workflows/write-epic.md
Output: Multi-file epic documentation.
Feature PRD Creation
When: User wants to document a feature within an existing epic.
Invoke: workflows/write-feature-prd.md
Output: Feature PRD.
Plan-Gated Refinement (PLAN/ACT/CHECK pattern)
When: Called automatically from refinement templates via PLAN GATE instruction.
Workflows (in workflows/plan/):
epic-ba-plan.md — Epic BA document selection decision treeepic-tech-plan.md — Epic tech document selection decision treefeature-ba-plan.md — Feature BA document selection (tier-aware, epic-incremental)feature-tech-plan.md — Feature tech document selection (contract-first)check-ba-docs.md — Shared BA validator: depth rules, pass/fail logiccheck-tech-docs.md — Shared tech validator: schema completeness, pass/fail logic
Epic Decomposition
When: A refined epic must be broken into features.
Invoke: workflows/decompose-epic.md
Output: Feature set with dependency ordering and traceability matrix.
Task Generation
When: Feature has completed architecture phase and needs implementation tasks.
Invoke: workflows/write-task.md
Output: A set of agent-executable task specs.
Template Resources
All workflows reference these template files for consistent structure:
context/epic-template.md — Epic document structure and sectionscontext/prd-template.md — Feature PRD structure and sectionscontext/task-template.md — Task structure and frontmattercontext/naming-conventions.md — File and directory naming standards
Quality Standards
All specification documents must:
- Be specific and actionable, avoiding vague language
- Include concrete examples where helpful
- Anticipate edge cases and error scenarios
- Define clear success metrics that are measurable
- Establish explicit boundaries to prevent scope creep
- Maintain consistent cross-references between files
For detailed usage instructions, see README.md
