Skip to content
Skills Library
Programming · Writing

spec-write

/spec-write

Start spec-driven work on Device by writing specs/NNN-slug/spec.md (problem, behaviour, requirements, acceptance checks, out of scope, open questions). Use when someone asks for a new feature, a behaviour change, cross-layer or performance work, or a format or C ABI change, before any code is written.

Repository
device ↗
Licence
AGPL-3.0
Last repository change
13.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 13.11.2026, without references to retired models or APIs.

Licence

AGPL-3.0, copyleft: przeróbki udostępniane innym muszą mieć tę samą licencję.

What it does and when to use it

Start spec-driven work on Device by writing specs/NNN-slug/spec.md (problem, behaviour, requirements, acceptance checks, out of scope, open questions). Use when someone asks for a new feature, a behaviour change, cross-layer or performance work, or a format or C ABI change, before any code is written.

Original author description

Start spec-driven work on Device by writing specs/NNN-slug/spec.md (problem, behaviour, requirements, acceptance checks, out of scope, open questions). Use when someone asks for a new feature, a behaviour change, cross-layer or performance work, or a format or C ABI change, before any code is written.

How it works

  1. 1. Decide whether this needs a spec
  2. 2. Learn the area before writing
  3. 3. Create the folder
  4. 4. Fill it in
  5. 5. Stop for agreement
Original SKILL.md headings · 52 lines, 453 words
SKILL.md preview
---
name: spec-write
description: Start spec-driven work on Device by writing specs/NNN-slug/spec.md (problem, behaviour, requirements, acceptance checks, out of scope, open questions). Use when someone asks for a new feature, a behaviour change, cross-layer or performance work, or a format or C ABI change, before any code is written.
---

# Write a spec

The spec says what we are building and why, in terms the maintainer can agree to. It does not say
how; that is `spec-plan`. Read `specs/README.md` and `specs/principles.md` first, and the finished
example in `specs/001-agent-skills-and-specs/`.

## 1. Decide whether this needs a spec

Typos, doc edits, obvious small fixes and behaviour-free refactors don't: make the change. Bugs
start with `bug-fix`; when `bug-fix` sends a bug here because its cause or fix is not obvious, carry
on below. Everything else gets a spec. If unsure, ask, or write a short one.

## 2. Learn the area before writing

Read enough code to describe today's behaviour accurately and to know which layers are involved:
`docs/architecture.md` for the overall shape, `docs/devices.md` for built-in devices, the ADRs in
`docs/adr/` for decisions already made, and the relevant section of `PROGRESS.md`. Run the app
(`cargo run --release -p dstudio-app -- --demo`) or render a review state if the change is visible.
A spec built on a wrong picture of today wastes everyone's review.

## 3. Create the folder

Take the next free number: `ls specs | grep -E '^[0-9]{3}-' | sort | tail -1`. Create
`specs/<NNN>-<short-slug>/` and copy `specs/_template/spec.md` into it.

## 4. Fill it in

- **Problem**: what is missing or wrong, for whom. No solution words.
- **Behaviour**: what the user sees and does, step by step, using the app's real names for menus,
  panels and controls. Include the undo label, what is saved with the project, and what happens
  with old projects.
- **Requirements**: numbered (R1, R2...), each testable on its own. Cover edge cases the user can
  reach: empty selection, very long or very short clips, sample-rate changes, missing media, undo
  in the middle of a gesture.
- **Acceptance checks**: numbered (A1, A2...), each naming the requirements it covers and how it is
  checked (a core or engine test, a self-test step, a review-state screenshot, a benchmark number).
  Every requirement is covered by at least one check.
- **Out of scope**: what a reader might expect that this deliberately leaves out.
- **Open questions**: every decision that belongs to the maintainer. Don't guess these; list them,
  with your recommendation for each.

Write in plain sentences. Describe behaviour in our own words: a product we study for reference is
a source of facts, never of text, art or code (principle 6).

## 5. Stop for agreement

Set `Status: Draft`, show the maintainer the spec and the open questions, and wait. When the
questions are answered, fold the answers into the spec, empty the Open questions section, set
`Status: Agreed`, and move on to `spec-plan`. Don't plan or write code before then, unless you were
told to run the whole workflow without stopping.

Versions

RepositoryScoreLicence
This page · devicedaw/device100AGPL-3.0
selhorys/dataspoke-baseline100Apache-2.0

Database snapshot: 13.11.2026 · package version d83eda3ca8b8 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 90sdlc-specify
    Create or update a feature specification (what and why, no implementation) in specs/NNN-slug/spec.md. Use for T3 features, when the user says 'spec this' or 'write a spec', or when requirements for existing behaviour change.
  • 100spec
    Asks the questions that change the design, then writes a spec in docs/specs/ with testable requirements and non-goals. Use for level-2 work (a new feature, or a change to more than ~5 files or more than one area) before any code; not for level 0-1 edits.
  • 100write-specs
    Use when the user needs to create or refine a feature SPEC SDD before implementation.
  • 100draft-spec
    Draft a lightweight feature spec — description, prior decisions, prioritised user stories, a task list, and a done-when checklist — into specs/NNN-slug/spec.md in a fixed format enforced by a checker script. Use whenever a feature should be specified before it is built — "spec…
  • 100implement-spec
    Implement a spec (specs/NNN-…) with the agentic pipeline - independent spec critique and impact map, tests written first and locked, implementation, deterministic checks, independent audit before push. Use when the user asks to implement a spec with /implement-spec, or to…
  • 100spec-driven
    WellForge spec-driven development conventions: the spec → plan → tasks workflow, file formats, status lifecycle, and drift rule. Use whenever working in a project that has a specs/ directory, when the user mentions a spec, feature specification, or task list, when implementing…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.