# Anyone - find your situation, say the line

Whatever your role, the situations below come up. Each one gives you the exact sentence and
says what happens underneath.

You never have to remember a skill's name - the agent recognises the situation from what you
said. Every case names the skill anyway, so you can call it directly on the days you know
exactly what you want.

The one rule under all of it: **specs are living specifications of the current
or target state - not archives, not wish lists** (ADR-002, ADR-024). Materials
go to [discovery](discovery.md), decisions to ADR/BDR, work items to the
backlog. The spec holds behavior.

## "I want the product to do something new" (PO)

```
> new feature: guests should be able to change their booking dates themselves
```

Saying "new feature" or "new story" first is for your benefit rather than the agent's - it
makes the line unmistakably an ask. The bare sentence works identically.

The agent starts the loop itself (the standard is AI-led, ADR-010): it checks
`docs/discovery/` for a related dossier, checks `specs/` for an existing
capability, then runs `/spec-specify`. You get a draft spec at
`specs/booking-changes/spec.md`, `Status: in-refinement` (the draft state),
with every gap as a typed open marker - a question (CLARIFICATION), a missing
decision (DECISION: ADR/BDR), a missing input (INPUT: e.g. UX design), a
missing asset (ASSET: e.g. credentials) - each naming who brings it. Then the
clarify loop asks you only what genuinely needs your call.

**Corner case - the capability already has a spec**: the agent updates
`specs/booking-changes/` **in place**. Same capability = same directory,
always (ADR-002); there is never a `booking-changes-v2/`. New behavior enters
an existing spec through the same specify/clarify round.

**Corner case - is this a new spec or a change to an existing one?** Ask what
capability owns the behavior, not what ticket asked for it. "Change dates" and
"cancel booking" both belong to the booking capability's boundary decisions -
when in doubt, say it and let the agent propose:

```
> does this belong in an existing spec or a new one? guests want to gift a booking to a friend
```

## "Something came out of a meeting" (anyone)

```
> notes from today's pricing meeting: <paste>
```

The extract (not the transcript) lands in `docs/discovery/<topic>/` with a
date+source stamp; contradictions with earlier entries get flagged. How the
dossier feeds specs - and why nobody ever re-answers an old question - is the
whole of [discovery.md](discovery.md). Had a meeting? Drop the extract. That
is the entire habit.

## "I have new information for an existing feature" (PO or dev)

```
> the provider settles refunds at T+3, not same day - update the booking-changes spec
```

The agent runs `/spec-impact` (what else does this touch?), then
`/spec-update` on every affected spec - in the same PR as any code change,
because the coupling guard blocks code-only changes to mapped capabilities
(R11). If the new fact contradicts a recorded decision, the agent proposes a
**superseding** record instead of silently editing the old one.

## "I am about to build it" (dev)

```
> plan booking-changes
```

`/spec-plan` refuses a spec that is not `ready-to-develop` - that status is
earned, not typed: the clarify gate script passes only when `## Clarifications`
exists and zero open markers of the family remain. So if planning is blocked,
the gate's output IS your to-do list: it names every open marker and its
owner. Chase those, not the plan. After that: `/spec-tasks`,
`/spec-implement`, and `/spec-reconcile` closes spec == code == tests and
flips the status to `live`.

## "What is left to do here?" (anyone)

```
> what is blocking booking-changes from development?
```

The agent runs the clarify gate and reads the markers back: "a BDR on
repricing (business), the UX flow (design), sandbox credentials (ops)". The
spec is the status report - no tracker archaeology.

## "I found the code does something the spec does not say" (dev)

```
> the code caps date changes at 3 per booking but the spec says nothing about it
```

That is drift. The agent fixes the spec if the behavior is intended and settled;
otherwise it records the gap as a typed marker in the section that owns it and the
item goes to the backlog - never a silent gloss (R13). Recording it in the spec is
not free, and that is deliberate: the clarify gate counts markers and reads
`## Open questions`, so a capability with an unresolved gap in its spec cannot be
planned again until the gap is resolved or moved to the backlog with a link. The
backlog is where work waits: items arrive from spec deltas, drift, and onboarding,
and leave only when their definition of done is met.

## What does NOT go into a spec

| You are holding | It goes to |
|---|---|
| meeting notes, mails, screenshots | `docs/discovery/<topic>/` - with provenance |
| the *why* of a fork you took | an ADR/BDR - the spec links it |
| "we should someday..." | `docs/ideas/` (may never ship) or the backlog (will) |
| plan/tasks scaffolding | ephemeral - removed at `live` (ADR-010) |
| the history of the spec | git - the spec describes the present (ADR-018) |

## The status walk (who flips what)

`in-refinement` (the draft state - open markers welcome, that is the point)
-> `ready-to-develop` (earned mechanically: the clarify gate passes)
-> `in-development` (plan/tasks/implement running)
-> `live` (reconciled: spec == code == tests; scaffolding cleaned).

A spec can sit in `in-refinement` for weeks while discovery runs - that is
healthy, and the markers keep it honest. What it must never do is reach
development with anything still open; the gate makes that a property of the
repo, not of anyone's discipline.