Ziw To Issues

To Issues

Turn planned work into implementation tickets that are ready to run and fit the plan. This is the single front door for creating implementation tickets. Every implementation ticket the workflow runs should pass through here, including ones the user created by hand.

To Issues creates and shapes tickets. It does not implement, review, or move active work. Spec or epic tickets are input containers, not work to ship.

Flows that file tickets outside To Issues, such as review sweeps or eval sessions, must either run this intake pass or leave readiness labels off so the gap stays visible. A hand-filed ticket carrying ready-for-agent without intake metadata is a dispatch hazard.

Inputs

• A spec doc, PRD ticket, epic ticket, plan, or project to turn into issues. A Grill-managed spec must be Ready for slicing.
• Repo path and docs/agents/workflow/config.md.
• Existing tracker tickets under the same parent, project, or route.
• Any hand-created implementation tickets to adopt into the plan.

Context

Read docs/agents/workflow/config.md first. If it is missing, run or request ziw-setup before creating tickets.

Confirm before creating or editing tickets:

• provider location, project, team, parent, and routing label
• status names, the configured ready state, and intake states
• kind label set and its single-select policy
• readiness, risk, type, and area labels and their policies
• estimate field, scale, and requiredness policy
• agent-ready issue body contract
• dependency and blocker fields
• file footprint convention from config

Read the agent-ready body contract and label rules from ../ziw-setup/references/issue-tracker-contract.md so the body shape and labels stay defined in one place. See Self-Healing below when existing tickets are inconsistent.

Planning Handoff

Inspect the source plan before creating or editing tracker tickets.

• Status: Ready for slicing, or its configured equivalent, is an explicit Grill handoff and may proceed.
• Status: Draft, or its configured equivalent, is not ready for implementation slicing. Stop and report its blocking questions.
• When the user explicitly asks to preserve a Draft in the tracker, create or update only a non-ready kind-spec or kind-epic container carrying the gaps. Do not emit implementation slices or apply ready-for-agent.
• A legacy spec, PRD, plan, or epic without lifecycle status may proceed only when its outcome, scope, non-goals, behavior, acceptance signals, and material open questions are clear enough to satisfy this skill's ticket contract.
• A contradiction or blocking question that could change slice boundaries, risk, dependencies, or required proof returns the plan to ziw-grill; To Issues does not invent the missing decision.

Do not weaken this gate because a plan already has tickets. Adopt existing tickets only after the source is ready enough to define their boundaries.

Ticket Kinds

Kind is a single-select axis, separate from type. Skills enforce exclusivity even when the tracker group does not.

• kind-spec: holds spec or PRD prose. Input to To Issues. Never dispatched.
• kind-epic: a parent or workstream container grouping slices. Never dispatched.
• kind-slice: one-PR implementation ticket. The only kind a worker runs.

Set exactly one kind on every ticket To Issues touches, and clear any other kind-* value.

Containers Are Input

Treat a kind-spec or kind-epic ticket as the source you turn into issues, not a ticket to ship.

• Read its prose, linked docs, and acceptance signals.
• Emit kind-slice children and link them under it.
• Keep the container as a container. Never put ready-for-agent on it and never hand it to a worker.

Adopt Before Creating

To Issues is idempotent. Re-running it over the same plan converges; it does not duplicate.

Before creating any ticket:

1. Inventory existing tickets under the target parent, project, or route, including hand-created ones.
2. Match planned slices to existing tickets by outcome, scope, and touched area.
3. Adopt each match: bring it up to the body contract, set kind-slice, fix labels and links. Do not create a duplicate.
4. Create new kind-slice tickets only for planned work that has no existing ticket.
5. When two existing tickets cover the same slice, converge on the canonical one and mark the other a duplicate; do not silently leave both. See Self-Healing.

Adoption fixes mechanics and fills missing contract headings from evidence in the plan. It never invents scope or acceptance criteria. Where intent is unknowable, apply needs-info and leave the exact question.

Slice

Cut work into thin, independently shippable, one-PR vertical slices.

• Each slice delivers a verifiable end-to-end behavior, not a layer.
• Each slice is scoped to one PR.
• Each slice has one primary outcome. Do not bundle "while you are there" cleanup, polish, adjacent bug fixes, future-proofing, or sibling ticket work into the same kind-slice.
• Prefer a tracer-bullet first slice that proves the path end to end, then slices that widen it.
• Do not make a kind-slice whose Done state requires multiple PRs. Split scaffold, CI gate, data migration, preview flip, and final wiring into separate slices or keep them under a kind-epic container so a first linked PR cannot falsely close the whole scope.
• When adjacent outcomes are useful but not required for this PR, create sibling slices, link them, and name them in this ticket's out-of-scope section.
• Leave vague ideas un-ticketed until scope is clear; record them as open questions rather than guessing scope.

Body Contract

Give every kind-slice ticket the agent-ready body from the issue tracker contract:

• outcome
• context docs, with spec citations when the slice comes from a spec
• likely files, packages, or artifacts
• in scope
• out of scope
• acceptance criteria
• required checks
• security, privacy, data, and operational invariants
• dependencies or blockers
• estimate when config stores estimates in the body

The in scope and out of scope fields are a hard boundary, not placeholders. Write them so an implementation worker can tell when to stop:

• in scope names only the behavior, files, docs, tests, and workflow state this PR may change.
• out of scope names tempting adjacent work, sibling ticket IDs when known, optional polish, broad refactors, production actions, and follow-up behavior the worker must not deliver.
• If out-of-scope cannot be written because the slice boundary is unclear, mark the ticket needs-info or keep it under a container. Do not mark it ready-for-agent.

If a required field is unknowable from the plan, add the heading, mark the ticket needs-info, leave the specific question, and do not mark it ready. Do not fabricate criteria to make a ticket look ready.

When the slice implements behavior defined in a spec, PRD, or ADR, cite the exact sections it implements in context docs as resolvable links, such as docs/specs/<file>.md#<section-anchor>. Use the section anchor as the traceability unit; do not paraphrase spec behavior into the ticket without the citation, and do not cite a whole document when specific sections apply. Verify each cited anchor resolves. A spec-derived slice without resolvable citations is not ready-for-agent.

Write acceptance criteria as proof obligations the implementer and reviewer can map one-for-one to evidence. If the requirement is structural, such as "derive, do not copy", "fail closed", "no production-path assertion", "real driver path", or "env var reaches the test process", name the exact behavior and regression test that must prove it.

Record deploy prerequisites, runtime secrets, hosted gates, generated artifact updates, and CI env passthrough requirements as explicit acceptance criteria or required checks. Do not bury launch blockers only in background docs.

When a slice depends on exact external config, resource IDs, provider names, label slugs, secret names, or environment values, put the exact configured literals or their config lookup location in the body. Do not rely on prior issue comments as the only source for hard values a worker must use.

Prefer slices that match known strong agent-fit work: docs, tests, build or CI updates, small refactors with clear checks, scoped bugs with reproduction, and isolated UI changes with target states. Mark high-risk or ambiguous work for human planning when the plan does not settle the security, product, data, or architecture decision.

For auth, bootstrap, claim, invitation, one-use grant, custody, or ownership slices, make the security invariants concrete before marking the ticket ready. Name the authenticated actor, tenant or resource binding, replay behavior, atomic consume or claim requirement, and concurrency checks the worker must prove.

For custody, persistence, driver-integration, or provider-integration slices, give acceptance criteria an executable shape that exercises the real boundary. Prefer checks such as multi-instance readback, concurrent first use, real driver queries, env passthrough, or provider-shape verification over prose-only assertions. Do not make a mock of the integrated seam the only proof.

For slices that drop or narrow schema on retained data, put the deploy order in the acceptance criteria: pre-deploy data cleanup must land before the schema change deploys when the platform validates the new schema against existing rows, and bulk migrations must use a resumable batched runner, not a single transaction. Name the production deploy status that proves the change landed; a green preview does not prove the production deploy.

Estimates

Follow the Estimate Rules in ../ziw-setup/references/issue-tracker-contract.md: estimate each kind-slice after splitting to one PR, using only the configured field and scale, and omit estimates when config defines none. If estimates are required before ready-for-agent and a value is unknowable from the plan, leave the exact question, apply needs-info or ready-for-human, and do not mark the ticket ready.

Labels And Readiness

For each kind-slice:

• apply one type and one risk label from config
• apply routing and area labels from config
• apply the configured estimate when the estimate policy grants To Issues that authority
• apply the configured worker environment label only when the environment approval criteria are met; dependency state is not a reason to withhold it
• apply ready-for-agent only when the slice is scoped to one PR, routed, type and risk labeled, estimated if required, has a concrete in-scope and out-of-scope boundary, and is complete enough to verify
• do not apply ready-for-agent when the body itself says human setup, credentials, provider decisions, or security judgment are still required
• place ready kind-slice issues in the configured ready state, usually Todo, even when they are blocked by other tickets; do not park implementation-ready slices in Linear Backlog
• otherwise apply needs-info or ready-for-human with the exact gap

ready-for-agent means no further human refinement is needed before agent handoff. It does not mean unblocked or startable. Blocked slices can still be ready-for-agent; encode the blocker separately.

Dependency Graph

Emit a dependency graph so the orchestrator can compute the ready frontier and run safe work in parallel.

• Encode dependencies with the tracker's relationship or blocker fields when the provider supports them; otherwise record them in the body in the configured shape.
• Use the configured relationship direction. By default, if ticket A needs ticket B first, A is blocked by B and B blocks A.
• Order slices so each depends only on earlier ones. Break cycles and report them.
• Serialize slices that must not run concurrently even without a direct data dependency, such as shared schema or migration ordering, using the configured dependency mechanism.
• When several slices converge on the same core files or regenerate the same shared artifact, sequence the convergent slice to land first or immediately adjacent to its siblings, or serialize the cohort. Same-base siblings all conflict the moment one merges.
• Encoding a dependency never removes ready-for-agent, the configured ready state, or a worker environment label.

File Footprint

For each kind-slice, record a predicted file or package footprint in the configured location and shape, so the orchestrator can avoid dispatching colliding slices concurrently.

• List the files, directories, or packages the slice is most likely to change.
• Include shared document surfaces the slice is likely to edit, such as dense markdown list blocks, status ledgers, registries, changelogs, config tables, and docs sections owned by many slices.
• Keep it a prediction, not a guarantee; the worker may diverge.
• Flag slices with heavy expected overlap so they are serialized or sequenced.
• Compare sibling slices after assigning individual footprints. Record hot files or packages and the safe fan-out pairs, so Orchestrator does not discover obvious collisions only after workers are already in flight.

Coverage Matrix

When the input is a spec, PRD, or a container that links one, emit a coverage matrix so dropped requirements are caught at slicing time instead of surfacing as drift after merge.

• Map every spec section that states requirements to exactly one of: the slice IDs that implement it, deferred with the reason and owning ticket, or an open question left as needs-info.
• Use the spec's section anchors as rows, the same anchors the slices cite in context docs. Do not invent a separate requirement numbering.
• Mark sections that state no requirements, such as overviews and narrative context, as not-applicable explicitly. An anchor absent from the matrix is an uncovered gap, not an implied skip.
• Record the matrix on the container ticket body, or in the location repo config names. Re-runs converge on the one existing matrix: update rows in place, never emit a second matrix for the same spec.
• The run is incomplete while any requirement-bearing section is unmapped. Report unmapped sections as gaps; do not mark the container's slices ready while the matrix has silent holes.

Self-Healing

Use model judgment over current evidence to repair stale or inconsistent ticket structure, escalate missing intent or authority, never leave a silent dead end, and record every fix. For To Issues specifically:

• Heal a wrong or duplicate kind-*, a stale label that resolves to a verified one, and a re-run duplicate by converging on the canonical ticket.
• Escalate with needs-info when scope or acceptance criteria are unknowable; never fabricate them to make a ticket look ready.
• Report every heal and every escalated gap in the run summary.

Guardrails

• Do not implement code, open PRs, merge, deploy, or move active work states.
• Do not ship or mark ready a kind-spec or kind-epic container.
• Do not duplicate existing tickets; adopt and converge.
• Do not invent scope, acceptance criteria, or product decisions.
• Do not create new label taxonomies or statuses without config or explicit user approval.
• Keep ticket text metadata-only. Never paste secrets, customer data, signed URLs, credentials, or private logs.

Done

Report:

• source plan and target location
• slices created, slices adopted, and duplicates converged
• kind labels set and any kind contradictions healed
• estimates set, preserved, omitted by policy, or left with exact questions
• tickets marked ready-for-agent, needs-info, or ready-for-human
• dependency graph and any cycles or required serializations
• file footprints recorded and overlaps flagged
• coverage matrix location, rows mapped, and any uncovered or deferred sections
• heals applied and intent gaps escalated, with exact questions left
• what the user must answer before the remaining slices can become ready