Skip to content
Skills Library
Management & product · Planning

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".

Repository
specweave ↗
Licence
MIT
Last repository change
27.10.2026

Assessment and security

84/ 100Class: good
Format9 / 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
2
Scripts
0
HTML comments
1
URLs in SKILL.md
0
Deprecation

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

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 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

plan a featurenew incrementlet

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

  1. Before writing
  2. Decide
  3. Create it
  4. spec.md
  5. Then
Original SKILL.md headings · 109 lines, 791 words
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.

Feedback and reports

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