design

Files (1)

• SKILL.md

SKILL.md (first lines)

# Design

Request: $ARGUMENTS

State the design for this request. Its job is to remove ambiguity and fix the contracts that separate pieces of work must agree on. It is not an implementation plan: tasks, file-by-file steps and code belong to `sdlc:split`.

Be precise only where two people implementing different parts could otherwise build incompatible things, or where the goal itself is unclear.

## 1. Find prior art

Invoke `sdlc:prior-art` with the request. It searches the configured docs sources, the repository, its beads and, with the user's permission, other connected sources, and reports each item with what it establishes and a `Searched` line.

For each item it returned, decide how the new design relates to it: **reuse**, **extend**, **replace** or **avoid**. Its open questions become yours.

If it found nothing relevant, say so; that is a valid result.

## 2. Remove ambiguity

List the open points whose answer would change a contract, a goal or the scope. Leave out anything prior art already settles, and anything that is an implementation detail.

Use the optional sections of step 3 as a checklist: an input, a data shape, a type, an error, a trigger or a schedule that two parts touch and nothing fixes yet is an open point.

- If you can ask the user, use AskUserQuestion: concrete options, recommended option first, at most 4 questions per round and 2 rounds.
- If you cannot ask (headless session, or the tool is unavailable), choose the most reasonable option and record it as an assumption.

## 3. State the design

State the design directly in your reply, in this form:

```markdown
# <Title>

<Summary in 2–4 sentences: what is being built and why.>

## Prior art

- `path` | `bead:<id>` | `<source>:<title or url>`: what it establishes. reuse | extend | replace | avoid.

(or "No prior art.")

Searched: <the Searched line from sdlc:prior-art>

<!-- Include only the sections that remove real ambiguity for this request. -->

## Goals and non-goals
## Definition of done
Observable outcomes, not steps.
## Glossary
## Inputs and outputs
For each part: what it receives (arguments, requests, files, events, environment) and what it produces (return values, responses, files written, events, side effects).
## Data
Entities and their fields, where each is stored, which part writes it, lifecycle and retention, expected volumes, migration of existing data.
## Contracts
Types, interfaces, data shapes, file formats, routes, commands, configuration, and their invariants. Exact wherever several parts must agree: signatures and field types, not prose.
## Errors and edge cases
Each failure a caller can see, how it surfaces (exit code, status, exception, message), and what is retried.
## Schedules and triggers
What starts each part (a command, a request, an event, a cron schedule, a hook), how often, in what order, its timeout, and what may run concurrently.
## States
The states a long-lived thing moves through, and the transitions between them.
## Constraints
Limits that bound the implementation: latency, size, cost, permissions, compatibility.
## Examples
Concrete inputs with the exact outputs they produce, at least one of them an error. Split turns them into acceptance checks and tests.
## Decisions
Each choice, the alternatives rejected, and why.

## Open questions and assumptions

- <question or assumption>: impact if wrong.
```

- Contracts that already exist in prior art are referenced, not restated.
- When this design changes something an earlier design defined, say so explicitly and name the earlier design.

**Doc edits:** list the changes existing files need because this design makes them wrong or incomplete — a README, an ADR, API docs, an earlier design. Each entry: the file, and what changes. Make the edits. This is the only side effect.

**A new document, only if the user asks for one:** write it to the location the request names; otherwise the repository's existing design-doc convention; otherwise `docs/design/<slug>.md`. The slug is short kebab-case derived from the request. If a design on the same topic already exists, update it instead of creating a second one.

## 4. Report

Print:
- a summary of at most three lines
- the assumptions you made
- the doc edits made, or that none were needed
- the new document's path, if the user asked for one

Then suggest `/sdlc:split` in the same session as the next step.

Do not create beads, branches or commits.

If plan mode is active, put the complete design — the stated design and the doc edits — in the plan file, and apply the doc edits (and write a new document, if asked for) once plan mode ends.

From Igosuki/agentic-sdlc, MIT.

More from Igosuki/agentic-sdlc