Tickets Batch

/tickets-batch — Bulk-File Structured Tickets

Read .claude/rules/writing-standard.md. Use the controlled technical writing profile for every filed ticket. Keep each ticket self-contained and concise.

The fast happy path for filing 5–20 tickets in one intent (project kickoff, roadmap decomposition, handover integration plan). Use this instead of raw gh issue create (non-conformant) or running /feature / /task / /bug N times serially (~10 questions × N tickets).

This skill is the fast happy path. Each ticket it produces conforms to the project's .ticket.required_sections schema by construction — never by post-hoc validation. The matching validate-issue-structure.sh hook is a backstop, not the primary fix.

Flow shape:

/tickets-batch
  → 1 shared-context Q batch (priority, epic, area-labels, repo)
  → N micro-interviews (≤ 3 Qs each: type, one-line purpose, optional clarification)
  → 1 confirmation
  → N `tracker_create` calls (one per ticket — never a single batch dump)

Path resolution

Read the registry path via portfolio_registry, the per-project docs dir via portfolio_projects_dir, and the ideas backlog via portfolio_ideas_backlog — all from .claude/hooks/_lib-portfolio-paths.sh. Source the helper at the top of any bash block that touches those paths:

source "$(git rev-parse --show-toplevel)/.claude/hooks/_lib-read-config.sh"
source "$(git rev-parse --show-toplevel)/.claude/hooks/_lib-portfolio-paths.sh"
registry=$(portfolio_registry)

Defaults match today's single-fork layout (./apexyard.projects.yaml, ./projects, ./projects/ideas-backlog.md). Adopters in split-portfolio mode override the portfolio.{registry, projects_dir, ideas_backlog} keys in .claude/project-config.json. Don't hardcode literal apexyard.projects.yaml or projects/ paths in bash blocks — the helper resolves whichever mode the adopter is in. See docs/multi-project.md.

Usage

/tickets-batch
/tickets-batch File 12 tickets for the auth refactor
/tickets-batch ./backlog-batches/handover-integration.md

The argument is free-form — a description, a markdown file path, or empty. Step 2 below normalises whatever you pass into a list of titles.

Process

1. Resolve the target repo

Read .claude/session/current-ticket to determine which repo we're working in. If absent:

• Scan apexyard.projects.yaml for managed projects.
• If only one project, use it.
• If multiple, ask: Which project is this batch for?
• If no projects are registered, ask for the repo in owner/repo format.

Confirm the resolved repo with the user before continuing — a wrong repo means N misfiled tickets, hard to undo.

2. Gather the batch

Accept ANY of these input shapes:

a) A list pasted in one message — numbered or bulleted, one title per line:

1. Wire OIDC discovery endpoint
2. Add session refresh to token middleware
3. Migrate user table to new auth schema
- Sweep deprecated /v1/login routes
- Add audit log for failed login attempts

b) A path to a markdown file containing the same — detect when $ARGUMENTS is a single token ending in .md or starts with ./ / / and points at an existing file.

c) Empty / a free-form description — ask:

Paste the list of titles, one per line, or give me a file path to read from.

Strip list markers (1., -, *, •, leading whitespace). Drop empty lines and lines starting with # (treated as comments / headings). The result is an ordered list of N titles.

Cap: if N > 20, stop and say:

That's {N} tickets — over the per-batch cap of 20. Split into batches of ≤ 20
and re-run /tickets-batch for each. (The cap exists to keep the confirmation
step reviewable; bumping it later is a config change, not a skill rewrite.)

If N < 2, suggest /feature / /task / /bug instead — this skill is overkill for a single ticket.

3. Shared-context questions — ASK ONCE for the whole batch

Ask conversationally, one question at a time, but only once for the entire batch — not per ticket:

a) Default priority

Read the priority scheme from .claude/project-config.json → .ticket.label_priority_scheme (fallback P0,P1,P2,P3). Present the values:

Default priority for this batch?
1. P0 — must-have for current milestone
2. P1 — ship soon
3. P2 — future
4. P3 — backlog
(Per-ticket overrides aren't asked — bulk-file flow trades per-ticket priority for speed.
Re-prioritise after filing if needed.)

b) Optional epic / parent ticket

Optional epic or parent issue to reference in every ticket body?
(e.g. #42, owner/repo#42, or Enter to skip)

If provided, every filed ticket body gets a Refs <epic> line at the bottom. If skipped, no parent reference is added.

c) Optional area labels

Area labels to apply to all tickets? (comma-separated, e.g. area-backend, area-auth)
(Or Enter to skip. Type-specific labels — enhancement, bug, etc. — are auto-applied per ticket.)

Validate that each label is a single token (no spaces). If a label looks risky (e.g. contains priority — would conflict with the priority label), warn and re-ask.

d) Repo confirmation

Echo the resolved repo and the count, and confirm before starting the per-ticket interviews:

Filing {N} tickets to {owner/repo}, default priority {P1}, area labels: {labels or "none"},
parent: {epic or "none"}.

Continue? (yes / change / cancel)

4. Per-ticket micro-interview

For each title in order, run a maximum-3-question micro-interview. Show progress: [Ticket 3 of 12].

Q1 — Type (always asked):

Read the whitelist from .claude/project-config.json → .ticket.prefix_whitelist (fallback Feature, Bug, Chore, Refactor, Testing, CI, Docs). Present numbered options:

[Ticket 3 of 12] "Migrate user table to new auth schema"
Type?
1. Feature — user-facing capability
2. Bug — broken behaviour
3. Chore — tech debt / housekeeping
4. Refactor — restructure without behaviour change
5. Testing — test coverage / fixtures
6. CI — pipelines / tooling
7. Docs — documentation

Accept the number or the type name (case-insensitive).

Q2 — One-line purpose (always asked):

One sentence on what this ticket does and why.
(Used to infer the body — User Story / Driver / Given-When-Then.)

Loop until non-empty. From the type + purpose, infer a draft body that conforms by construction to .ticket.required_sections[<type>]:

Every section must be non-empty — empty sections fail validate-issue-structure.sh. Always emit a placeholder (TBD: <hint>) rather than an empty header.

Q3 — Optional clarification (asked ONLY if inference is low-confidence):

Inference is low-confidence when:

• Feature: the purpose has no clear persona AND no clear "so that" benefit
• Bug: the purpose has no clear trigger ("when X happens") AND no clear broken behaviour
• Chore / Refactor / Testing / CI: the purpose has a why OR a what but not both

In those cases, ask one targeted question:

If inference is confident, skip Q3 and move on.

After Q1–Q3, show the inferred body inline (compact form, 4–6 lines) and continue to the next ticket without asking for confirmation per ticket — full-batch confirmation happens at step 5.

5. Show batch summary and confirm

Display all N tickets in a compact table:

Batch summary — {N} tickets to {owner/repo}:

| #  | Type     | Title                                              | Priority | Labels                  |
|----|----------|----------------------------------------------------|----------|-------------------------|
| 1  | Feature  | Wire OIDC discovery endpoint                       | P1       | enhancement, area-auth  |
| 2  | Feature  | Add session refresh to token middleware            | P1       | enhancement, area-auth  |
| 3  | Chore    | Migrate user table to new auth schema              | P1       | area-auth               |
| ...
| 12 | Testing  | Add OIDC integration tests                         | P1       | area-auth               |

Parent: #42

Confirm? (yes = file all / edit N = re-interview ticket N / cancel = abort)

Handle the response:

• yes → proceed to step 6
• edit N (e.g. edit 3) → jump back to step 4 for that ticket only, then re-show the summary
• cancel / no → abort, no tickets filed, no state written

Do not file any ticket before this confirmation. Partial commits-before-confirm are forbidden — a misclick at the summary should leave the tracker untouched.

6. File the batch

For each ticket in order, run a specific tracker_create call — one call per ticket, NEVER a single bulk JSON dump. The validator runs per-issue, so per-issue calls are the only conformant shape. Dispatch through tracker_create (#670 / AgDR-0072, extended by the #709 creator sweep) so the tickets land in this project's tracker — GitHub, GitLab, or a custom CLI. For a GitHub adopter each call runs gh issue create exactly as before.

Build the title as [<Type>] <title>. Build the body from the inferred sections, ending with the optional Refs <epic> line if a parent was set.

# Resolve + source the tracker lib ONCE, before the loop, by walking up from cwd.
tracker_lib="$(r="$PWD"; while [ -n "$r" ] && [ "$r" != / ]; do \
  [ -f "$r/.claude/hooks/_lib-tracker.sh" ] && { echo "$r/.claude/hooks/_lib-tracker.sh"; break; }; \
  r="${r%/*}"; done)"
# shellcheck source=/dev/null
. "$tracker_lib"

# ── per ticket ──────────────────────────────────────────────────────────────
body_file="$(mktemp)"
cat > "$body_file" <<'BODY'
{formatted body}
BODY
# tracker_create <owner/repo> <title> <body_file> [<labels_csv>] → {"ref","url"}.
result="$(tracker_create "{owner/repo}" "[{Type}] {title}" "$body_file" "{type-label},{priority},{area-labels}")"
rc=$?
rm -f "$body_file"
# rc=3 → tracker.kind=none (shape-only); rc!=0/empty → hard failure (see step 7).
ref="$(printf '%s' "$result" | jq -r '.ref // empty')"   # e.g. 451 — used in the progress line

Type-label mapping:

Show progress per call, using the ${ref} parsed from each tracker_create:

[1/12] Filing "Wire OIDC discovery endpoint"… → owner/repo#451 ✓
[2/12] Filing "Add session refresh to token middleware"… → owner/repo#452 ✓

7. Failure handling

On the first tracker_create failure (rc non-zero or empty result), stop the batch immediately. Do not silently skip. (A tracker.kind=none project returns rc=3 with the rendered body on stdout — treat that as "shape-only, nothing filed" and stop the batch the same way, telling the operator to file the set in their external system.) Show:

[5/12] Filing "Migrate user table to new auth schema"… ✗

Error from the tracker CLI / validator:
{stderr — usually the validator's "missing section: Driver" line}

Filed so far: 4 tickets ({owner/repo}#451, #452, #453, #454).
Remaining: 8 tickets (not filed).

What now?
1. Retry — re-run the same tracker_create call (use this if the failure was transient)
2. Skip — drop this ticket, continue with the next 7
3. Edit — re-interview this ticket and retry
4. Abort — stop here; the 4 already-filed tickets stay (no rollback)

Do not roll back already-filed tickets on abort. Tell the user exactly which ones did file — they can close the unwanted ones manually if they choose, but silent rollback would be worse than partial completion.

8. Return the summary

One line per created ticket:

Filed {N}/{total} tickets to {owner/repo}:

#451 — Feature — Wire OIDC discovery endpoint — https://github.com/{owner}/{repo}/issues/451
#452 — Feature — Add session refresh to token middleware — https://github.com/{owner}/{repo}/issues/452
#453 — Chore   — Migrate user table to new auth schema — https://github.com/{owner}/{repo}/issues/453
...

Skipped / failed: 0
Next: prioritise with the team, then `/start-ticket <N>` to begin work.

If any tickets were skipped or failed, list them under a separate Skipped / failed: section with the failure reason for each.

Body templates (per type)

These are the exact shapes the inferred bodies must take. Each section header must be non-empty (placeholders allowed) so validate-issue-structure.sh passes.

Feature

## User Story
As a {persona}, I want {goal} so that {benefit}.

## Acceptance Criteria
- [ ] {criterion derived from the purpose}
- [ ] TBD — refine before starting work

{Refs <epic> if set}

Chore / Refactor / Testing / CI

## Driver
{why this is needed — derived from the purpose}

## Scope
{what changes — derived from the purpose, or "TBD: define before starting work"}

## Acceptance Criteria
- [ ] {criterion derived from the purpose}
- [ ] TBD — refine before starting work

{Refs <epic> if set}

Docs

## Driver
{why these docs are needed — derived from the purpose}

## Acceptance Criteria
- [ ] {criterion derived from the purpose}
- [ ] TBD — refine before starting work

{Refs <epic> if set}

Bug

## Given / When / Then
**Given** {precondition derived from purpose, or "TBD"}
**When** {trigger derived from purpose, or "TBD"}
**Then** {broken behaviour derived from purpose, or "TBD"}

## Repro
- [ ] TBD: add concrete repro steps

{Refs <epic> if set}

Rules

1. ASK shared-context questions ONCE at the start (priority, epic, area-labels, repo). NEVER re-ask them per ticket.
2. Per-ticket interview is at most THREE questions: type, one-line purpose, optional clarification. If the type + purpose yield a confident inference, skip the third question.
3. Output conforms to .ticket.required_sections by construction. Never produce a body that the validate-issue-structure.sh hook would reject. Every required section is present and non-empty (placeholders allowed); section headers match the schema spelling exactly.
4. One tracker_create per ticket. NEVER a single batch-mode JSON dump — the validator runs per-issue and a bulk shape silently bypasses it. (For a GitHub adopter each call is a gh issue create.)
5. Confirm the full batch BEFORE filing any ticket. No partial commits-before-confirm. A cancel at the summary leaves the tracker untouched.
6. On failure mid-batch: stop, surface the validator error, ask the user. Don't silently skip. Don't roll back. Tell them exactly which tickets did file.
7. Cap at 20 tickets per invocation. Above that, ask the user to split into batches.
8. argument-hint: "<optional bulk description>" — accept a free-form description, a markdown file path, or empty input. Normalise to a list of titles in step 2.
9. Read schema from project-config. Use .ticket.prefix_whitelist, .ticket.label_priority_scheme, and .ticket.required_sections from .claude/project-config.json (with defaults from .claude/project-config.defaults.json). Don't hard-code the schema in the skill — config drives.
10. Leak protection still applies. When the target repo is the public framework repo (e.g. me2resh/apexyard), never let a ticket title or body reference a registered private project name. The block-private-refs-in-public-repos.sh hook will reject such calls; the skill's job is to not produce them in the first place.
11. No silent edits to existing tickets. This skill creates only. To modify an existing ticket, use gh issue edit directly or open a follow-up.
12. Defaults are sane, not magical. If the inference produces a placeholder (TBD: …), say so in the summary table — don't pretend the body is complete. The user can edit N to refine before filing.

Part of ApexYard — multi-project SDLC framework for Claude Code · MIT.