Scope Ticket

---
name: scope-ticket
description: Turn a thin or vague ticket into one you can write a failing test from, before any branch is cut. Use when about to implement a ticket whose description is underspecified, when asked to scope/refine/groom a ticket, or when a task lacks clear acceptance criteria or a defined entry point. The bar is a single question - could you write a red test from this cold? If not, it is not ready to implement.
---

# Scope a ticket to "Ready"

A ticket is Ready when someone with no prior context could write a failing test
from it and know exactly when it is done. Most defects that reach production
trace back to a ticket that was implemented while still ambiguous: the agent
guessed, and the guess shipped. Scoping first is cheaper than re-work.

Do not cut a branch on a ticket that is not Ready. Scope it, or push it back.

## Fill every section

Work the ticket into these six sections. If you cannot fill one, that gap is
the thing to resolve before implementing.

1. **Behavior.** What the system should do, in the user's terms, not the
   implementation's. One or two sentences. If you cannot state it without naming
   internal functions, the requirement is not understood yet.

2. **Acceptance Criteria.** Specific, testable statements. Each one must map to a
   test you could write now. "Works correctly" is not a criterion; "an anonymous
   visitor sees the price from the database, not the template default" is.
   Include the values, labels, and states that matter.

3. **Entry Points.** Where a real user reaches this, in concrete clicks or
   routes. This is the guard against the most common silent failure: shipping a
   column, a function, a component, or a CSS class that nothing wires to a
   user-visible surface. If the entry point is undefined, the feature is not
   scoped, it is half-imagined.

4. **Edge Cases.** Empty states, error states, boundaries, permissions, the
   unauthenticated path, the too-many and the zero cases. Name the ones that
   apply; note the ones you are deliberately not handling.

5. **Out of Scope.** What this ticket explicitly does NOT do. This is what keeps
   the implementation from sprawling and what protects the next ticket's turf.

6. **Implementation Boundary.** Name the repository/runtime boundary that can
   enforce the requested behavior. Record any required root-owned installation,
   distinct UID, daemon, container, cloud resource, migration, or operational
   rollout. If one is required but not authorized in this ticket, split or defer
   it; a repository-local approximation does not make the ticket Ready. For
   orchestration host controls, record the configured `worker_trust_profile`.

## Required adversarial test matrix

Before declaring Ready, derive a matrix whose rows contain: attack/failure mode,
setup or input, invariant/expected result, test layer, and the assertion that
would fail for a plausible bug. Select categories from the actual surface, but
explicitly consider parser/interpreter variants (including shell wrappers,
substitutions, heredocs, redirections, and pipelines), ignored/untracked state,
failed inspection commands, partial execution, cleanup/recovery, permissions,
concurrency, retries, boundary values, and hostile input. A category may be N/A
only with a concrete reason. This matrix is part of Ready and must exist before
a branch is cut or production code is edited.

## The readiness test

After filling the sections, ask the one question that decides it:

> Could a fresh implementer write a failing test from this, today, without
> asking a clarifying question?

- **Yes** -> Ready. It can be pulled into implementation.
- **No** -> Not Ready. The specific missing piece (an unstated value, an
  undefined entry point, an ambiguous behavior) is the next thing to resolve.
  Resolve it or send the ticket back; do not paper over it with a half-feature.

## Output

Produce the ticket rewritten into the six sections and the adversarial test
matrix, then state the verdict
(Ready / Not Ready) and, if Not Ready, the exact gap that blocks it. If the
repo's `rules_docs` define a ticket template or extra required fields (a
surface-area label, a definition-of-done clause), honor that template too.

When the sprint controller requests a scope assessment, also write a repository
artifact using this schema so the result can be scheduled without interpreting
prose:

```json
{
  "schema_version": 1,
  "ticket": "PROJ-123",
  "verdict": "ready | decompose | operator_decision | tracking_parent",
  "complexity_score": 0,
  "prerequisites": [],
  "children": [],
  "reasons": ["evidence-based reason"],
  "slices": [
    {
      "id": "stable-short-id",
      "summary": "independently releasable slice",
      "behavior": "user-visible or system behavior",
      "acceptance_criteria": ["testable outcome"],
      "migration_owner": "none",
      "test_plan": ["specific regression test and expected result"],
      "depends_on": []
    }
  ]
}
```

Use `decompose` when the ticket crosses multiple independently releasable
boundaries or cannot reasonably complete design, implementation, and review
inside one ticket budget. Produce two through the repository's configured
`max_auto_slices` slices. Each slice must be safe to merge independently and
must assign migration ownership, rollout ordering, and security invariants in
its behavior or acceptance criteria. Use `operator_decision` only when slicing
would choose product behavior or weaken a required invariant; ordinary
technical decomposition is not a human decision.

Each slice must include `migration_owner` (the owning slice ID, or `none` when
no migration is needed) and a nonempty `test_plan`. These fields are validated
and copied into the Jira child description.

Before returning `ready`, enumerate every prerequisite found in the ticket text in
`prerequisites` (an array of ticket keys, empty only when none exist). Compare them
with the supplied scheduler dependencies. A missing relationship requires dependency
reconciliation before implementation, never speculative work.

For a tracking parent whose work is entirely owned by its already-existing children,
return `tracking_parent`, empty `slices`, and `children` containing exactly the
authenticated child keys. Do not create another decomposition or reserve an
implementation lane to discover the parent disposition. If the parent has independent
acceptance criteria beyond those children, do not classify it as tracking-only.