ValentinNikolaev/agent-skills / agent-plugins/skills/write-spec
write-spec
VerifiedDraft testable requirements and boundaries for a proposed change. Use to create a specification; not to review one or verify code against it.
Write a Specification
Draft a compact, implementable contract before a significant change. Adapted from Addy Osmani's spec-driven-development workflow; see the bundled license and repository third-party notice.
Route precisely
- Use when the user requests a specification, PRD, or explicit requirements for a proposed feature or substantial change.
- Use
review-specto judge an existing draft,api-and-interface-designwhen the primary deliverable is one interface contract,planning-and-task-breakdownto order implementation work, andverify-implto compare finished code with authoritative requirements. - Do not require a specification for a mechanical edit. Do not start implementation merely because the spec is written.
Establish authority and scope
Read the user's requested outcome, repository instructions, related contracts, existing behavior, and any binding decision records. Separate confirmed facts from proposed behavior and assumptions. Ask only for information that determines a material product or safety choice; otherwise make a clearly labeled draft assumption.
Draft the contract
- State the problem, intended users or consumers, objective, and scope. Identify what behavior is explicitly excluded when that prevents ambiguity.
- Break a broad requirement into independently testable capabilities. For each, describe inputs, outputs, state changes, defaults, failure behavior, and the owner of the data or side effect where relevant.
- Specify public interfaces, compatibility, authorization, trust boundaries, migration, concurrency, and recovery only to the level needed for this change. Do not invent a mandatory technology stack or file layout.
- Give each material obligation an observable acceptance criterion. Include examples and edge cases that resolve otherwise plausible divergent implementations.
- Record unresolved decisions with their consequence and the evidence or owner needed to settle them. Do not disguise an open decision as an accepted requirement.
Deliver and check
Return the draft in the requested format or in chat. Check it for contradictions, unstated dependencies, untestable terms, and unsupported claims about current code. State what is confirmed, proposed, and unknown. A completed spec is ready for review-spec or planning; it does not establish implementation correctness.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |