Create Scoped Tickets Skill

Create Scoped Tickets

Seed or extend a GitHub label-scoped universe of mutually exclusive Agent Work Tickets from a technical implementation spec.

Seed - the label universe is empty. Decompose the spec into the first N tickets.
Append - the label universe already has tickets. Decompose the spec, then only draft what is not already covered. Where the spec overlaps an existing open ticket, propose amending that ticket instead of filing a duplicate.

Tickets are drafted as text first, presented as one set for one batch approval, then each approved new ticket is filed via gh issue create.

Fits into the workflow

Seed or extend the boundary set - create-scoped-tickets creates or extends the labeled Agent Work Ticket universe.
Scope the design and plan - scoped-planning consumes selected ticket numbers to scope brainstorming, plan grilling, and implementation-plan writing.
Route review findings - scoped-differential-review consumes selected ticket numbers to classify PR findings against the ticket universe.
Execute a completed plan - ship-from-plan executes the completed plan produced downstream; it does not take ticket numbers as a direct input.

The Agent Work Ticket headings are a repository-local schema. Seed establishes the format using the Agent Work Ticket template; Append expects the recognized headings when parsing existing tickets. Downstream skills use the ownership and exclusion headings (The owner may, The owner must not, Scope of Work, Not In Scope) to build scope boundaries; Definition of Done is also part of the recognized structure. Preserve the template's structure when creating or amending tickets.

Requirements

The gh CLI authenticated against REPO, with permission to read issues and create new issues.
At least one usable label. If a requested label does not exist, report it and ask whether to create it via gh label create; never create a label without confirmation.
A readable spec source.

Glossary

Agent Work Ticket - a GitHub issue with exclusive ownership, exclusions, dependencies, and verifiable completion criteria.
Label universe - all open issues in the repository carrying any requested label.
Scope map - the ownership and exclusion boundaries extracted from those issues.
Amendment proposal - text-only suggested changes to an existing issue; this skill never applies them automatically.

Inputs

SPEC - the technical implementation spec. A file path (e.g. docs/spec.md), a URL, or pasted content. Required.
REPO - GitHub repository hosting the ticket universe, e.g. org/project. Required.
LABELS - one or more labels that define the target universe, comma-separated (e.g. topic1 on first seed; topic1,topic2 when appending on a second run). Required. Every drafted ticket is filed with all listed labels.
SCOPE_HINT (optional) - one sentence narrowing the slice of the spec to decompose in this run. Omit to decompose the whole spec.

Bare ticket numbers in later cross-references require REPO; REPO cannot be inferred from a spec path.

Built-in defaults (never restated by the user)

Exclusive ownership: every drafted ticket's "The owner may" scope is disjoint from every other drafted ticket and from every existing open ticket in the union of LABELS.
Overlap-resolves-to-amendment: when the spec's next chunk overlaps an existing open ticket, propose amending that ticket (concrete text diff) rather than filing a duplicate.
Draft-first, batch approval: never call gh issue create before showing the full drafted set and receiving one approval.
Stubs and dependencies over folding: when a drafted ticket needs work owned by another drafted or existing ticket, specify the stub or interface and record the dependency; never pull the other ticket's work into this one.
No mutations besides filing: this skill never edits, closes, or relabels existing issues. Amendment proposals are text only.

Workflow

Copy this checklist and check off phases as you complete them:

Ticket Progress:
- [ ] Phase 0: Universe inventory (scope map, Seed/Append mode)
- [ ] Phase 1: Spec decomposition
- [ ] Phase 2: Overlap classification (Append mode only)
- [ ] Phase 3: Draft tickets
- [ ] Phase 4: Present drafts for batch approval
- [ ] Phase 5: File approved NEW drafts

Phase 0 - Universe inventory

List all open issues carrying any of LABELS in REPO:

for label in <LABELS>; do
  gh issue list -R <REPO> --label "$label" --state open --limit 200 --json number,title,body,labels
done

Deduplicate by issue number.

For each existing ticket, parse the recognized scope-section headings and extract:
- Owned scope from "The owner may" or "Scope of Work".
- Excluded scope from "The owner must not" or "Not In Scope".
The authoritative set of recognized headings is: The owner may, The owner must not, Not In Scope, Scope of Work, Definition of Done. If a ticket uses none of these, see Error handling.
Build the scope map: {ticketNumber -> {title, labels, owned, excluded}}. This is the boundary set drafted tickets must not cross.
Classify the universe state:
- Empty: zero open tickets under LABELS. Enter Seed mode.
- Non-empty: one or more open tickets. Enter Append mode.

Phase 1 - Spec decomposition

Read SPEC in full. Identify the atomic units of work it prescribes. Each unit becomes at most one ticket candidate. Group only where a single owner would reasonably deliver the whole group in one PR sequence.

Constraints on the candidate set:

Every candidate's outcome traces to a concrete section of SPEC. Cite the section path (e.g. docs/spec.md §3.7).
Candidates are mutually exclusive: no work item appears in two candidates.
Candidates are collectively complete for the region of SPEC in scope (governed by SCOPE_HINT if given).
Candidates are ordered so that dependencies land before dependents; note dependencies explicitly.

Phase 2 - Overlap classification (Append mode only)

For each candidate, classify against the Phase 0 scope map:

NEW - candidate's owned scope is disjoint from every existing ticket. Draft it as a new ticket in Phase 3.
AMEND - candidate's owned scope overlaps an existing open ticket's "The owner may" or Definition of Done. Do not draft a new ticket. Draft an amendment proposal for the existing ticket: the concrete text to add or refine (Request/Outcome bullets, Scope of Work bullets, DoD items, Source Materials links), citing the spec section.
PARTIAL - candidate's owned scope partially overlaps an existing ticket. Split the candidate:
- The overlapping slice becomes an AMEND proposal.
- The non-overlapping slice becomes a NEW candidate whose "The owner must not" explicitly cites the existing ticket by number.

Any two NEW candidates must also be mutually exclusive. If they overlap, merge them or resplit their boundaries before Phase 3.

Phase 3 - Draft tickets

For each NEW candidate, write an Agent Work Ticket using the template below.

Scoping rules per ticket:

Every bullet under "The owner may" must trace to the candidate's slice of SPEC. If a bullet cannot be traced, delete it.
"The owner must not" is the most important section. Build it from the union of the Phase 0 scope map and the sibling NEW candidates in this run: name each ticket (existing by number, sibling by draft label like [draft #A]) whose scope borders this one.
Where the ticket depends on another ticket's unimplemented work, specify the stub or interface to code against (name the interface and the owning ticket) and record the dependency in Background / Context.
Definition of Done must be verifiable without any other ticket's unimplemented work; tests may use stubs.

Ticket template

Title: <Area> - <Concrete outcome> (e.g. Besu Sidecar - Builder 2PC: collapse lock-gap-lock pattern).

Do NOT include Status, Status Flow, Required Receipt, or Due Date in the body. Status is tracked via labels/project; receipt via PRs opened.

## Agent Work Ticket

### Request / Outcome

What needs to happen?

* <Bullet the outcomes, not a vague theme. Concrete verbs + named components.>

### Background / Context

Relevant context the owner needs to understand the task.

* <Why this exists: prior PRs, reviews, design constraints.>
* <Dependencies on other tickets: "Depends on #N (consumed via <interface/stub>); blocked by #M landing first.">

### Source Materials

Attach or link the materials needed to complete the task.

* <Specs, PRs, commits, adjacent tickets. Prefer repo-relative paths, e.g. docs/spec.md §3.7.>

### Scope of Work

The owner may:

* <Allowed work. Every bullet traces to the Request / Outcome.>

The owner must not:

* <Out-of-scope work item> (ticket #N)
* <Out-of-scope work item> (ticket #M or [draft #A])
* <Change shared interfaces/contracts owned elsewhere>
* <Invent semantics not in the spec/source materials>
* Take any action requiring human approval without asking first

### Definition of Done

This ticket is complete when:

* <Verifiable checks only: tests, invariants, docs. If it cannot be checked, it is not DoD.>

### Stop Conditions

Stop and ask for input if:

* Ambiguity or missing information in the spec or interfaces
* A decision requires product/protocol judgment
* An action would affect another team or repo
* There is risk of overstepping the ticket scope

### Blocking Questions

If blocked, ask only the exact question needed to continue.

* <Pre-seed only if already known; otherwise leave empty.>

Phase 4 - Present drafts for batch approval

Emit the full drafted set as text in this order:

Universe snapshot: label(s), REPO, mode (Seed / Append), existing-ticket count.
Coverage map: which spec section maps to which drafted ticket letter ([draft #A], [draft #B], ...) or to which existing ticket (AMEND #N).
New ticket drafts in dependency order, each shown in full.
Amendment proposals grouped by target existing ticket number, each showing the concrete text to add.
Uncovered spec sections if any (spec content that mapped to neither a NEW candidate nor an AMEND proposal). Ask the user to confirm they are intentionally out of scope.

Ask one approval question with three permitted answers:

Approve all - proceed to Phase 5 and file every NEW draft.
Approve subset - the user names the drafts to file; the rest are held.
Revise - the user gives feedback; return to Phase 3.

Amendment proposals are handed to the user as text regardless of approval choice.

See references/worked-example.md for a complete Seed-mode example of this output.

Phase 5 - File approved NEW drafts

For each approved NEW draft, run:

gh issue create \
  -R <REPO> \
  --title "<Title>" \
  --body "<full Agent Work Ticket body>" \
  --label "<label1>" --label "<label2>" ...

Include every entry in LABELS. Capture the returned issue number and URL.

After all filings, print a receipt: for each draft letter, the assigned issue number and URL, or "held" if not filed. If any filing fails, stop and report; already-filed tickets remain filed.

Author checklist (per drafted ticket, before Phase 4)

[ ] Outcome is specific enough to implement without guessing product intent
[ ] Sources cite concrete spec sections
[ ] "The owner may" bullets each trace to SPEC
[ ] "The owner must not" cites every adjacent ticket in the universe (existing by number, sibling by draft letter)
[ ] DoD is testable without other tickets' unimplemented work
[ ] Stop conditions cover the real judgment calls
[ ] Dependencies on stubs/interfaces are recorded in Background / Context

Error handling and edge cases

Input errors

SPEC cannot be read (path missing, URL fetch fails) -> stop, report the error, ask for a working source.
REPO not supplied -> stop, ask for REPO. Do not infer from spec path.
LABELS not supplied -> stop, ask for at least one label.
A label in LABELS does not exist on REPO -> report which; ask whether to create it via gh label create (do not create without confirmation).

Universe-inventory errors

An existing ticket carrying a label in LABELS has none of the recognized scope-section headings -> report which ticket(s); ask the user for its owned/excluded scope in one line each. Never infer scope from a ticket title alone.
Two existing tickets appear to own the same area -> report the pair with numbers; ask the user which owns it before decomposing. Do not silently pick one.

Decomposition errors

SPEC yields zero decomposable units -> stop, ask whether SCOPE_HINT should be widened or the spec is genuinely out of scope for this label.
After Phase 2, every candidate is AMEND -> emit only amendment proposals; skip Phase 5 (nothing to file); tell the user the spec is fully covered by existing tickets and the amendments are optional refinements.
A candidate cannot be split cleanly around an existing ticket boundary -> flag the pair; ask the user to redraw the boundary before proceeding.

Filing errors

gh issue create fails on a draft -> report the error; stop before the next filing; already-filed tickets remain filed and their numbers are printed.
Network / auth failure before any filing -> stop; nothing is filed.

Invocation

Invoke this skill with:

$create-scoped-tickets <SPEC> --repo <OWNER/REPO> --labels <label1>[,label2,...] [--scope-hint "<one-sentence hint>"]

Examples:

$create-scoped-tickets docs/spec.md --repo org/project --labels topic1
$create-scoped-tickets docs/spec.md --repo org/project --labels topic1,topic2 --scope-hint "only §4 (execution layer)"

Verification

Static checks and scenario exercises for maintaining this skill live in references/verification.md. Run the static checks after editing this SKILL.md.

Agent Skills: Create Scoped Tickets

Install this agent skill to your local

Skill Files