LiorCohen/sdd / plugin/core/skills/spec-writing
spec-writing
VerifiedTemplates and validation for writing product specifications.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 2.2 KB |
| resources/epic-spec-template.md | markdown | 1.9 KB |
| resources/feature-spec-template.md | markdown | 4.4 KB |
| resources/frontmatter-validation.md | markdown | 3.3 KB |
| resources/other-templates.md | markdown | 2.0 KB |
| schemas/input.schema.json | config | 1.1 KB |
| schemas/output.schema.json | config | 1.3 KB |
resources/frontmatter-validation.md
View on GitHub# Frontmatter Fields and Validation Rules
## Tech Spec Frontmatter (Default)
Every tech spec (generated SPEC.md) must include:
```yaml
---
title: Change Name
spec_type: tech # Required: tech (default for generated specs)
type: feature | bugfix | refactor | epic
status: active | deprecated | superseded | archived
domain: Identity | Billing | Core | ...
issue: PROJ-1234 # Required: JIRA/GitHub issue
created: YYYY-MM-DD
updated: YYYY-MM-DD
sdd_version: X.Y.Z # Required: SDD plugin version used
supersedes: [optional, path to old spec]
superseded_by: [optional, path to new spec]
---
```
**Required fields for tech specs:**
- `title`
- `spec_type` -- Must be `tech`
- `type` -- Must be `feature`, `bugfix`, `refactor`, or `epic`
- `status`
- `domain`
- `issue` -- Must reference a tracking issue
- `created`
- `updated`
- `sdd_version` -- Plugin version used to generate this spec
**Required sections for tech specs:**
- `## Overview`
- `## Acceptance Criteria`
- `## API Contract` (if type involves API changes)
- `## Domain Model`
- `## Requirements Discovery` (Q&A trail from solicitation)
- `## Testing Strategy`
## Product Spec Frontmatter
External/product specs have minimal requirements:
```yaml
---
title: Product Spec Name
spec_type: product # Required: product
status: active | archived
domain: Identity | Billing | Core | ...
created: YYYY-MM-DD
updated: YYYY-MM-DD
---
```
**Required fields for product specs:**
- `title`
- `spec_type` -- Must be `product`
- `status`
- `domain`
- `created`
- `updated`
**Optional sections for product specs:**
- `## Overview`
- `## User Stories`
- `## Requirements`
- `## Acceptance Criteria`
## Validation Rules
Run `<plugin-root>/system/system-run.sh spec validate <path>` to check:
- Required frontmatter fields present based on `spec_type`
- Acceptance criteria in Given/When/Then format (tech specs only)
- All referenced definitions exist in domain glossary
- Required sections present (tech specs only)
- Open questions resolved (no BLOCKING open questions remain)
## Validation Error Messages
Validation should return clear, actionable error messages:
```text
Spec validation failed: changes/2026/02/05/a1b2c3-user-auth/01-auth/SPEC.md
FRONTMATTER ERRORS:
- Missing required field: issue
- Missing required field: sdd_version
- Invalid spec_type: 'unknown' (expected: tech | product)
SECTION ERRORS:
- Missing required section: ## API Contract
- Missing required section: ## Requirements Discovery
FORMAT ERRORS:
- Line 45: Acceptance criterion not in Given/When/Then format
Found: "Users can register"
Expected: "Given [precondition], when [action], then [result]"
OPEN QUESTIONS (BLOCKING):
- O1: What's the rate limit for login attempts?
- O2: Should failed logins trigger alerts?
Resolve these questions before spec can be approved:
/sdd I want to answer an open question
/sdd I want to answer an open question
```
## Open Questions Block Approval
Specs CANNOT be approved while open questions remain in the `## Requirements Discovery` section. The validation enforces this:
| Question Status | Effect |
|----------------|--------|
| `OPEN` | Blocks spec approval |
| `ANSWERED` | Does not block |
| `ASSUMED` | Does not block (assumption documented) |
| `DEFERRED` | Does not block (requires justification, tracked for later) |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |