increment
/increment
Plan work as a SpecWeave increment - one spec.md with Problem, Scope, numbered ACs, Approach and Tasks - before writing code. Use for "plan a feature", "new increment", "let's build X".
- Author
- anton-abyzov ↗
- Repository
- specweave ↗
- Licence
- MIT
- Last repository change
- 27.10.2026
Assessment and security
- Files in this package
- 2
- Scripts
- 0
- HTML comments
- 1
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
- SKILL.md zawiera komentarze HTML (1). Nie widać ich w podglądzie Markdown, a model je czyta.
What it does and when to use it
Plan work as a SpecWeave increment - one spec.md with Problem, Scope, numbered ACs, Approach and Tasks - before writing code. Use for "plan a feature", "new increment", "let's build X".
Triggers from the description
Arguments
/increment \"<title>\" [--supersedes NNNN]
Original author description
Plan work as a SpecWeave increment - one spec.md with Problem, Scope, numbered ACs, Approach and Tasks - before writing code. Use for "plan a feature", "new increment", "let's build X".
How it works
- Before writing
- Decide
- Create it
- spec.md
- Then
SKILL.md preview
---
description: Plan work as a SpecWeave increment - one spec.md with Problem, Scope, numbered ACs, Approach and Tasks - before writing code. Use for "plan a feature", "new increment", "let's build X".
argument-hint: "\"<title>\" [--supersedes NNNN]"
metadata:
version: "3.1.0"
---
<!-- Generated from skills/sw-increment/SKILL.md by scripts/build/generate-skills.mjs. Edit the source, then npm run build. -->
# sw-increment: plan the unit of work
An increment is one folder, `.specweave/increments/NNNN-slug/`, with one file you write:
`spec.md`. `ledger.jsonl` beside it holds task state and is only appended to;
`metadata.json` is machine state you never need to read. One increment is one branch
and one PR.
## Before writing
- A small self-contained fix needs no increment. Just do it.
- An open increment already owns the files this touches (`specweave task list`)? Add
ACs and tasks to its spec.md instead of opening another.
- Read the code the change touches before writing Approach. If `GLOSSARY.md` exists,
write the spec in its terms.
- Unsure what to build at all, or the user says "grill me": run sw-grill-me first.
## Decide
Intent first: settle what the user wants and how a machine will check it before
writing ACs. `planning.deepInterview` sets the depth: `critical` (default) as below,
`deep` runs sw-grill-me, `off` states defaults and asks nothing.
1. **Think first.** Read the code and config; settle every fact yourself.
2. **Triage** each open decision: *fact* (look it up, never ask), *my call*
(reversible or low impact: pick a default), *theirs* (hard to reverse, costly, taste).
3. **Ask** only "theirs", at most 5, highest impact first. Each gets one clause on why
it matters and 2 to 4 options, your recommendation first; "yes" accepts it. Use your
tool's structured question tool when it has one. A clear request asks nothing.
4. **Record** in `## Decisions`: Asked, Defaulted (list every default: one the user
never saw is one they could not reject) and Open. Keep a line only when a later
change could contradict it: hard to reverse, surprising without context, or a real
trade-off. Apply each answer to Scope, ACs and Approach.
## Create it
`specweave create-increment "Add rate limiting"` prints the new folder with a scaffolded
spec.md; replace every `[bracket]`. Add `--supersedes 0031` when this replaces an older
increment (that one is abandoned for you), `--planned` for backlog work.
Manual path (no CLI): next id = highest folder number + 1, zero-padded to 4. Create
`NNNN-kebab-slug/` with `spec.md`, an empty `ledger.jsonl` and this `metadata.json`:
```json
{"id":"0042-ledger-fold","status":"active","type":"feature","created":"2026-09-02T10:00:00Z","lastActivity":"2026-09-02T10:00:00Z"}
```
Write UTF-8 without a BOM; in PowerShell use
`[IO.File]::WriteAllText($p, $body, [Text.UTF8Encoding]::new($false))`, never `>`.
## spec.md
```markdown
# 0042 Ledger fold
## Problem
Two agents can both believe they own T-01. Who hits it, and the evidence.
## Scope
In: claim ordering, malformed lines. Out: a ledger server.
## Acceptance Criteria
- [ ] AC-01: Two agents claiming the same task never both get it
- [ ] AC-02: A malformed ledger line is skipped and counted, never fatal
## Approach
Files that change and in what order, decisions, rejected alternatives, risks.
## Decisions
### Asked
- D-01 Claim tie-break? → earliest ledger line wins (user).
### Defaulted (change any before sw-do)
- D-02 Malformed-line report → a count in `task list` (reversible).
### Open
- none
## Tasks
### T-01 Fold the ledger
- AC: AC-01 | Files: src/core/tasks/ledger.ts, tests/e2e/double-claim.e2e.ts | Test: npm run test:e2e -- double-claim
### T-02 Skip malformed lines
- AC: AC-02 | Files: src/core/tasks/ledger-parse.ts, tests/e2e/malformed-ledger.e2e.ts | Test: npm run test:e2e -- malformed-ledger
```
- ACs are observable: "p95 of /search under 300 ms with 10k rows", not "faster".
- Every AC is covered by at least one task; every task names its `Files` and a `Test`
command a machine can run.
- A `Test` checks the AC from the outside: the CLI, HTTP route, UI or public API a user
or caller touches, run with the repo's own test command. A new test file goes in the
task's `Files`. Reuse existing tests; plan new unit or integration tests only when the
user, the project's `testing` config or its conventions ask for them. The
human-approved AC is the oracle, not a test the agent wrote.
- `Files` is the ownership unit: two tasks that edit one file cannot run in parallel,
so merge them. Shared contracts (types, schema) go in an early task.
- An AC is met when every task covering it is done. Nobody ticks the boxes; never
write state into spec.md.
- `plan.md` is optional overflow for a genuinely large design.
## Then
Show the ACs and tasks. Unless the user asked to review the plan first, carry on with
sw-do (one agent, or parallel lanes for three or more disjoint groups of tasks).
Opening an increment makes closing it part of the same job: any plan or checklist you
show ends with "Verify and close 0042", and sw-do closes it through sw-done once the last
task is done. When the plan waits for the user's review, say the increment stays open
until they answer.
Files in this package (2)
- SKILL.md 5 KB
- agents/openai.yaml 1 KB
Versions
The database has no other skills named increment.
Database snapshot: 13.11.2026 · package version 51b91e774e9e (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
- 84sw-increment
Plan work as a SpecWeave increment - one spec.md with Problem, Scope, numbered ACs, Approach and Tasks - before writing code. Use for "plan a feature", "new increment", "let's build X". - 84done
Close a SpecWeave increment - every task done or skipped, specweave verify green, a fresh-context review, then specweave complete. Use for "close it", "we are done", "finish up". - 90write-spec
Write a feature design spec with numbered acceptance criteria before any plan or code. Use when starting any feature, or when a request is too vague to build without guessing. - 100sprint-review
Facilitates the Sprint Review by presenting the increment, inspecting progress toward the Product Goal, and capturing Product Backlog adaptations. Use when anyone says things like "sprint review", "demo prep", "what did we complete this sprint", "review the increment", "what's… - 90feature-edit
Use when an in-flight feature must change — scope shifts, an AC is refined, the plan evolves, a behavior is added or removed. Triggers — "/engineer.feature-edit", "change feature X to", "the ACs need updating", "revise the plan", "scope changed". - 90pfb-spec-new
Draft a new feature specification (requirements.md, design.md, tasks.md) in specs/NNNN-feature-name/ through an iterative question-first conversation. Use when the user wants to spec, scope or plan a new feature before writing code.