write-spec
Draft feature specifications, requirements documents, user stories, acceptance criteria, and validation-ready specs from a feature request. Use this skill when you need to write a spec, define requirements, capture user stories, or produce a structured specification document.
- License 许可
- MIT
- 最近更新
- 2026-11-15
- Stars
- ★ 0
- Forks
- 1
01 前言 Front Matter
- name
- write-spec
- source
- DevSpark — © 2026 Make Bold Solutions. Source: https://dev.makeboldspark.com
- metadata
- { "version": "0.1.0" }
- description
- Draft feature specifications, requirements documents, user stories, acceptance criteria, and validation-ready specs from a feature request. Use this skill when you need to write a spec, define requirements, capture user stories, or produce a structured specification document.
02 资源文件 3
- 参考文档references/spec-template.md3.0 KB
- 脚本scripts/gather-context.ps13.1 KB
- 脚本scripts/gather-context.sh3.6 KB
03 SKILL.md 正文
write-spec
Draft a structured feature specification from a user's feature request. This skill works in any skills-compatible client with or without DevSpark installed.
Context Loading
Before drafting, run the context-gathering script for your platform:
- PowerShell:
scripts/gather-context.ps1 - Bash/macOS/Linux:
bash scripts/gather-context.sh
Parse the JSON output. If the script exits non-zero, produces empty output, or produces non-JSON output, use this fallback and continue without blocking:
{
"constitution_summary": null,
"prior_specs": [],
"skipped_context": ["script-error"]
}
The JSON output contains:
constitution_summary— key constraints from the repo constitution, or nullprior_specs— list of prior spec summaries for naming and scope awarenessskipped_context— list of context items that could not be gathered
If constitution_summary is non-null, apply the listed constraints to the spec.
If prior_specs is non-empty, use the existing numbering pattern for the new
spec and avoid duplicating solved problems.
Drafting Procedure
Use the spec template in references/spec-template.md.
- Set
namefrom the feature request. Generate a sequential number if prior specs are available (e.g., if the last spec was004-..., use005-). - Set
status: Draftalways. Do not set any other lifecycle state. - Write the Product Owner TLDR — a short non-technical summary that clearly states WHAT this spec changes and WHY it matters now.
- Write the Rationale Summary — core problem, decision summary, key drivers, tradeoffs considered.
- Write User Stories — at least one per priority tier in the request. Each story must have: actor, capability, business value, and acceptance scenarios.
- Write Requirements — MUST-level functional requirements as the minimum viable set. Do not add requirements the user has not implied.
- Write Success Criteria — measurable outcomes. Each criterion must be verifiable without DevSpark installed.
- Add an Assumptions section listing anything the spec takes for granted,
including any context items listed in
skipped_context. - Add an Out of Scope section. Capture anything explicitly not covered by this spec.
Do NOT include implementation details (frameworks, library versions, file paths). Keep the spec technology-agnostic.
Limit [NEEDS CLARIFICATION] markers to three. Use them only for genuine
blocking ambiguities that would prevent drafting a section.
Clarification Format
When a [NEEDS CLARIFICATION] marker is needed, follow this format:
[NEEDS CLARIFICATION]: <question>
Context: <why this matters for the spec>
Options: <list 2-3 concrete options when possible>
Consolidate related ambiguities into one marker. Do not add markers for stylistic preferences or implementation decisions.
Output
Produce a single spec.md file in the current working directory (or the path
provided by the host client). The file must:
- Pass the shared spec validation contract (see
references/spec-template.md) - Have valid YAML frontmatter with
status: Draft - Contain a
Product Owner TLDRsection that answers WHAT and WHY at a high level - Contain the four mandatory full-spec sections: Rationale Summary, User Stories, Requirements, and Success Criteria
- Contain no more than three
[NEEDS CLARIFICATION]markers - Contain no implementation details (no language choices, no library versions)
Do not perform branch creation, file moves to governed paths, checklist generation, or gate enforcement. Those are DevSpark-command responsibilities.
Assumptions Section
In the produced spec.md, always include an Assumptions section that lists:
- Any context gathered or not gathered (from
skipped_context) - Any decisions made without user input
- Any scope boundaries inferred rather than stated
04 同仓库更多 Skills
devspark-roadmap
Optional roadmap planning. Establish product direction, record and right-size Prospective Specs, review delivery evidence for drift, and keep the roadmap structurally consistent, without touching code, tests, or Knowledge.
devspark-roadmap
Optional roadmap planning. Establish product direction, record and right-size Prospective Specs, review delivery evidence for drift, and keep the roadmap structurally consistent, without touching code, tests, or Knowledge.
team-helper
Unrelated team skill
devspark-specify
Team-authored skill that happens to use a managed name
devspark-retired-demo
Previously generated skill whose command is no longer shipped
devspark-next
Detect the next lifecycle step