to-tickets git:20260908.1fabaadA

Immutable. This exact content is served forever at /api/v1/blob/c62cdda4f3215c7e.

---
name: to-tickets
description: Turn approved work into well-scoped GitHub issues after checking for duplicates and dependencies.
---

# To Tickets

Turn existing context into one or more focused GitHub tickets that can be implemented and verified independently.

## Principles

- Use facts from the user, source material, and repository. Do not invent requirements, goals, metadata, relationships, or priority.
- Preserve requirements, constraints, decisions, rationale, meaningful edge cases, and verified findings from prior research. Do not compress away technical detail that would force the implementation agent to repeat exploration.
- Make each ticket self-contained enough to complete without reading a parent or sibling. Reference relevant existing specs, ADRs, or repository docs when they exist; do not require or invent one.
- Keep cohesive work together. Do not split a useful ticket merely to make it smaller.
- Split only when a ticket has become too broad to implement or review coherently, contains outcomes that can deliver value independently, or needs safety-driven sequencing. When splitting feature work, prefer end-to-end slices that include every layer needed for the behavior without inventing work.
- Declare only genuine blocking dependencies. Sequence or preference alone is not a blocker.
- Do not modify or close a source or parent issue unless the user explicitly asks.
- Avoid generic file inventories and speculative code paths. Include confirmed code locations as current starting points when they save meaningful exploration, but do not present them as authoritative scope.

## GitHub access

- Use `gh` for issue creation, labels, native relationships, and verification.
- When a GitHub connector is already available, it may be used for repository, issue, pull-request, or review-thread reads. Use `gh` for all writes in one publication; do not mix connector and CLI writes.
- Resolve the exact `HOST/OWNER/REPO` from an explicit identifier or the local remote and retain that host for CLI and API calls. The helpers accept `OWNER/REPO` using `GH_HOST` when set, otherwise `github.com`. Ask only when the repository remains ambiguous after local inspection.
- Check the active account on the resolved host with `gh auth status --active --hostname HOST`. The helpers perform this check themselves. Diagnose failure for that host; request `gh auth login --hostname HOST` only when authentication needs repair. An unrelated account's status must not block publication.

## Process

### 1. Gather context

Work from the conversation and any referenced plan, spec, issue, comments, repository documentation, ADRs, domain glossary, or prior research. Inspect the codebase only as needed to make the tickets accurate. Ask only when unresolved ambiguity would materially change the ticket set, semantics, or dependency graph.

When the user explicitly asks to turn pull-request feedback into tickets, retrieve thread-aware review context through an available connector or `python "<skill-path>/scripts/fetch_review_context.py"`. Treat unresolved, non-outdated threads as candidates, but check them against the current code: unresolved feedback may already be addressed. Consult resolved, outdated, duplicate, top-level, and review-summary comments only as needed for context or unthreaded actionable feedback. Do not create implementation tickets for feedback that is already addressed, not actionable, or unclear; surface the disposition and use a research or decision ticket only when that outcome is itself explicitly requested.

List the repository's existing labels with their descriptions. Use descriptions and established usage on comparable issues to understand the repository's label vocabulary; do not infer semantics from a label name alone when its meaning is ambiguous.

### 2. Check for duplicates

Before drafting new tickets, search both open and closed issues for likely duplicates of each intended outcome. Use the plan's plain-language concepts rather than relying on one exact title. Read plausible matches closely enough to compare their actual goals and scope.

Surface likely duplicate URLs and explain the overlap. Do not treat a similar title as proof of duplication, and do not modify, close, or substitute an existing issue without the user's approval. Issues already created for this same approved ticket set are reused when resuming publication, after verifying their identity and current state. If the duplicate search cannot run, report why; do not create new issues until it succeeds or the user explicitly approves proceeding without it.

### 3. Draft the ticket set

Write each ticket as a compact argument that lets a busy maintainer understand the situation, judge its importance, and act without reconstructing the surrounding conversation. Use simple technical language and a specific, outcome-oriented title that makes sense on its own. Avoid shorthand, clever wording, and jargon that does not improve precision.

Use only sections that add information. A simple ticket may need only a summary, desired outcome, and acceptance criteria; omit empty sections and do not create both a simple summary and a second summary. Choose from these sections as the work requires:

- `## Summary`: explain in a short paragraph what is currently true, why it matters, and what should happen next; do not merely restate the title
- `## Why this issue exists`: when the ticket is derived from other work or needs justification as a separate unit, explain why it is distinct and worthwhile rather than only naming its source or classification
- `## Evidence` or `## Current behavior`: record verified observations, relevant code locations, constraints, and decisions; distinguish confirmed facts from hypotheses
- `## Impact`: state the concrete user, operational, or maintenance consequence and calibrate urgency honestly, including when the work is non-blocking or protects only against a future regression
- `## Desired outcome`: describe what should become true without prescribing files, code, or implementation details unless the source material already decided them
- `## Acceptance criteria`: use ordinary bullets describing independently verifiable behavior; do not use task-list checkboxes, implementation steps, code locations, generic “tests pass” statements, or bullets that merely restate the desired outcome
- `## Research and findings`: use this instead of a basic evidence section when prior exploration is substantial, preserving rejected approaches, pitfalls, and technical detail that would otherwise have to be rediscovered
- `## Risks / non-goals`: capture meaningful compatibility risks, scope boundaries, and nearby work that must remain untouched; omit generic boilerplate
- `## Context`: place source issues, pull requests, specifications, ADRs, and other provenance at the end so they support rather than interrupt the issue

Add another section only when important maintainer-facing information does not fit these concepts. Calibrate the language to the status of the work: state confirmed requirements directly, but present optional suggestions as tradeoffs rather than pretending implementation has already been decided. When the honest outcome is a maintainer decision, state the decision and evidence needed and allow the suggestion to be closed with a clear rationale.

Prefer cohesive, independently useful vertical slices with enough scope and context to act on. A ticket set may contain exactly one issue. Split only when the resulting tickets are easier to execute, verify, or sequence—not to meet an arbitrary size target. Allow enabling work, migrations, infrastructure, and mechanical refactors when those are the honest units of work. For a genuinely wide migration, describe the expand, consumer-migration, and old-path-removal stages in that order.

Allow research or investigation tickets when discovery is itself explicitly requested, independently useful work with a concrete question and completion signal. When the user asks for an actionable implementation ticket set for a feature believed to be ready, resolve material unknowns before drafting; do not turn them into research tickets that postpone implementation.

Do not create a tracking, overview, epic, or coordination issue merely to organize the set or preserve shared context. Attach tickets to an existing parent only when the user explicitly requests it or established repository convention requires it.

Let consumer and rollout evidence determine how an interface replacement is ticketed. When one coordinated change controls every consumer, keep the replacement cohesive and remove the old path in that ticket. When compatibility or rollout constraints require overlap, split the work into introduction, consumer migration, and removal. Record the removal condition for each temporary adapter and include the final cleanup ticket. Do not assume an interface is internal or invent a branching strategy without evidence.

Choose the smallest useful set of existing labels for each ticket. Select labels that accurately describe its type, affected area, or other established repository dimensions. Add priority, workflow, or ownership labels only when the source material and repository convention support them. Do not invent labels, force a label from an unsuitable taxonomy, or apply labels merely because their names share words with the ticket. If no existing label fits, leave that dimension unlabeled and surface the taxonomy gap.

Treat `ready-for-agent` as a readiness state, not a default ticket category. Apply it only when all of the following are true:

- the ticket calls for a concrete implementation or repository change, rather than research as its outcome
- the relevant decisions, constraints, context, and completion signals are sufficient to begin
- the work specified by the ticket does not depend on live human judgment, conversation, approval, access provisioning, or manual action

Do not apply `ready-for-agent` to research, investigation, discovery, or spike tickets; decision or coordination work; human-owned tasks; or underspecified implementation. Normal codebase exploration needed while implementing a well-specified change does not by itself make a ticket a research task.

Treat readiness and dependency status as separate dimensions. A fully specified, agent-executable ticket may carry `ready-for-agent` while an open native blocked-by relationship prevents it from starting. Represent that dependency only with the native relationship; do not withhold `ready-for-agent` merely because the ticket is blocked.

Check the current request and prior approvals for authorization to publish the concrete ticket set, including its repository, content, labels, and native relationships. Approval may already be supplied by a direct request to publish that set or by an earlier explicit approval of the drafts. Reuse that authorization when the set remains within its approved scope; do not require another turn solely because publication is the next step.

When content, metadata, duplicate handling, or publication authority still requires a decision, present the exact drafts and affected choices before asking for the missing approval. Include a short rationale for proposed labels and for including or omitting `ready-for-agent`. Approval of the drafts includes their listed labels and native relationships. Approval of an underlying feature alone is not permission to publish issues, and material changes to an approved set require approval of those changes.

### 4. Publish

If any part of this ticket set was already attempted, reconcile that state using [Resume partial publication](#5-resume-partial-publication) before making further writes.

Preflight `gh`, authentication, the repository, and every approved label. If an approved label is missing, report the affected tickets and ask for the missing decision; do not create or silently substitute a label. Continue only operations whose content and metadata remain authorized. Use `gh issue create` with a body file so Markdown and real newlines are preserved.

Create approved blockers before their dependents, then:

- create each approved issue
- apply exactly the approved labels for that issue
- create approved parent/sub-issue relationships with GitHub's native relationship
- create approved blocked-by/blocking relationships with GitHub's native relationship

After each creation, retain a compact mapping from the approved draft to its repository, issue number, and URL, with pending label or relationship operations. Record uncertain outcomes as uncertain until read-back establishes what happened. Keep this progress in the task context or an explicitly requested record; do not add tracking comments or labels solely to support retries.

For native relationships, run the bundled helper after both issues exist. It retrieves the required database IDs and verifies the relationship:

- parent: `python "<skill-path>/scripts/set_issue_relationship.py" --repo HOST/OWNER/REPO --parent PARENT_NUMBER --sub-issue CHILD_NUMBER`
- blocked by: `python "<skill-path>/scripts/set_issue_relationship.py" --repo HOST/OWNER/REPO --blocked BLOCKED_NUMBER --blocked-by BLOCKER_NUMBER`

Both issue numbers in a helper call belong to the named repository. Relationship verification compares database IDs, including when existing relationships point to issues in other repositories. For an approved cross-repository relationship, use host-scoped `gh api` with each issue's verified database ID rather than passing another repository's issue number to the helper.

Never propose, create, or assign a `blocked` label, including spelling or case variants. Never use a label or body link as a fallback for a failed native blocking relationship.

### 5. Resume partial publication

Resume the approved set rather than starting a new publication:

1. Re-establish the latest approved content and metadata. Read back known issue numbers or URLs and their current bodies, labels, and native relationships. Verify that each issue belongs to the intended repository and approved draft.
2. If a create request failed or returned no clear identifier, inspect current and recent repository issues to establish whether it succeeded. Compare the actual content and available creation context, not just the title. Reuse a verified match. If identity or creation status remains uncertain, report that gap instead of issuing another create request for the same ticket.
3. Preserve issues already created for this set. Skip verified completed operations and finish only missing approved labels or native relationships. Preserve unrelated edits and metadata added by others. If an issue was closed or materially changed, reconcile that state before attempting a repair; do not reopen, overwrite, delete, or recreate it merely to restore the earlier draft.
4. Create only tickets confirmed not to exist, retaining the duplicate checks and blocker-before-dependent ordering. Use the existing issue numbers for all remaining native relationships. Inspect a failed relationship operation before retrying it; never replace it with a label or body-only dependency.
5. Verify each resumed write and update the progress mapping. Continue independent authorized operations when one ticket is blocked, and report the remaining decision or failure without claiming the entire set is complete.

### 6. Verify and report

Verify every created or reused issue, approved label, and native relationship. Return the issue URLs and relationship status. If publication is partial, identify created or reused issues, completed operations, confirmed pending work, and uncertain outcomes, with the exact failure. Do not discard successful work or use destructive retries or semantic fallbacks to make the report appear complete.