Issue Triage
Issue Triage manages the issue tracker backlog so Orchestrator can run. It turns
tracker items into well-shaped, dependency-aware, agent-ready work or explicit
human/To Issues follow-up.
The end state is a useful Todo backlog:
- every
Todo implementation ticket is a one-PR kind-slice
- ready work has
ready-for-agent, the configured route, required labels,
required estimate, complete body contract, and predicted footprint
- blocked ready work stays in
Todo with blocker relationships encoded
- not-ready work is labeled or moved to the configured human, intake, parked, or
To Issues path when config grants that authority
- Orchestrator can consume the final
starts, blocked-ready list, and next
actions without re-triaging the same queue
Default triage starts from the configured ready and intake states plus direct
blockers only. In most Linear repos this means Todo, Triage, and any active
issues that directly block those tickets. Do not include unrelated Linear
Backlog, Duplicate, Done, canceled, icebox, or other parked/terminal states by
default.
This skill is script-driven tracker grooming. It is not research,
implementation, code review, repo health monitoring, CI diagnosis, deploy
diagnosis, security scanning, or production triage.
Read only:
docs/agents/workflow/config.md
- source-of-truth specs, roadmap, milestone, and project docs cited by the
config or scoped tickets
- issue tracker metadata, bodies, comments, labels, statuses, estimates,
projects, parents, and relationships
- explicit user instructions
- approved workflow script outputs from
skills/ziw-orchestrate/scripts
Run the scripts, read the output, inspect only the bounded tracker scope and its
cited source-of-truth docs, then fix the tickets. The scripts are the observation
layer for queue, PR, and worker state; the agent does not rediscover that state
manually. No manual code search, implementation file reads, one-off gh
queries, CI spelunking, deploy checks, log review, security tool runs, or broad
repo health checks. If handoff quality depends on information that is not in the
tracker, config, cited source-of-truth docs, or script output, leave the exact
missing field for To Issues or a human.
Tracker/MCP tools are for applying ticket mutations and reading specific ticket
fields that the scripts do not return. Do not use MCP calls to rebuild the same
inventory, PR state, dependency frontier, or readiness decisions that the scripts
already compute.
Inputs
- Issue tracker project, team, repo label, board, roadmap, query, filter, or
explicit Linear
Backlog state scope.
- Repo path and
docs/agents/workflow/config.md.
- Existing tracker statuses, labels, priorities, estimates, dependencies,
parents, children, duplicates, issue bodies, and comments.
- Optional user instructions for dry run, first-run intake backfill, first-run
Linear Backlog backfill, Linear Backlog review, intake cleanup, priority
policy, or orphan routing.
Context
Read docs/agents/workflow/config.md first. If it is missing, run or request
ziw-setup before broad cleanup.
Confirm these config values before mutating the issue tracker:
- provider location, project, team, roadmap, and routing label
- status names and mappings
- ready state, intake states, active states, done state, and Linear Backlog
policy
- readiness, type, risk, review-debt, worker environment, and route labels
- readiness label policy and startable work criteria
- priority policy, estimate policy, dependency policy, and orphan policy
- agent-ready issue body contract
- Issue Triage mutation authority
- dependency graph mechanism and blocker relationship direction
If tracker metadata disagrees with config, update only exact label gaps that are
safe to create. Do not create or rename workflows, statuses, teams, projects,
boards, roadmaps, or label taxonomies without explicit approval.
Operating Loop
Start each run by choosing one mode:
- default backlog grooming
- explicit issue, project, board, repo label, team, query, or filter
- requested Linear Backlog or intake cleanup
- dry run
A normal ziw-triage invocation is a request to process the configured intake
states. Complete implementation-ready intake tickets move from Triage to the
configured ready state, usually Todo, without requiring the user to separately
say "intake cleanup." Linear Backlog remains excluded unless explicitly
requested. A dry run recommends the same transitions without applying them.
Then follow this order:
- State the bounded tracker scope, skipped states, allowed mutations, and
ready/Done rules from config.
- Run the configured workflow scripts before broad tracker reads:
../ziw-orchestrate/scripts/tick-snapshot.mjs for the compact queue snapshot,
../ziw-orchestrate/scripts/tick-plan.mjs for deterministic queue decisions,
and ../ziw-orchestrate/scripts/linear-dag-start.mjs for
dependency/startability. In default mode, pass the configured ready and intake
states to tick-snapshot.mjs, usually --linear-states Todo,Triage, so the
script returns only those states plus their direct blockers. If a script cannot
run because credentials or inputs are missing, report the exact missing input
and use tracker tools only for the smallest bounded replacement query.
- Build the issue set from script output and tracker queries. Read cited
source-of-truth docs when needed to verify scope or dependency order.
- Freeze the issue set. Do not expand it because a linked PR, branch, CI run,
deploy, alert, or code path looks interesting.
- Classify every issue.
- Apply safe tracker updates in batches.
- Re-run the DAG/startability script over the updated issue set when
implementation
kind-slice issues are in scope.
- Report what changed, what remains blocked, and exactly what Orchestrator,
To Issues, or a human should do next.
If the issue set is empty, report the empty scoped result and stop.
Decision Routine
Use script and tracker output to choose one action per issue:
- Fix now: safe label, status, body, estimate, route, dependency, stale
readiness, review-evidence, or handoff-field repair is clear.
- Ready for Orchestrator: the issue is a one-PR
kind-slice with body,
route, readiness, required estimate, dependency encoding, and predicted
footprint.
- Blocked but shaped: the issue is otherwise ready, but
linear-dag-start.mjs reports dependency blockers.
- Needs To Issues: the issue is a container, vague plan, multi-PR scope,
missing split, or missing predicted footprint.
- Needs human: product, security, credential, customer, ADR, ownership,
priority, or acceptance-criteria decision is missing.
- Orchestrator action: script output shows linked PR/status/check/review
state needs active workflow handling that triage should not perform.
- Park: the tracker state is intentionally outside the current work queue.
Do not invent a new investigation path. If the next action is not one of these,
record a config gap or ask a specific human question.
Use the script outputs directly:
tick-snapshot.mjs gives the compact queue, linked PR footprint, current heads,
checks, review state, and Linear queue metadata when credentials are available.
tick-plan.mjs gives ready-state promotions, review-evidence actions,
human-merge label actions, capacity/dispatch signals, and the deterministic
next workflow action.
linear-dag-start.mjs gives roots, frontier, starts, blockers, cycles, and
missing startability requirements.
Triage owns ticket repairs implied by those outputs. Orchestrator owns active
delivery actions implied by those outputs.
Default Scope
Default triage is Todo plus intake grooming in the tracker. Build the default
issue set from configured tracker state and script output, not from ad hoc
exploration:
- Issues in the configured ready state, usually
Todo.
- Issues in configured intake or review-debt intake states that config says
Issue Triage should normalize, usually
Triage.
- Direct active blockers of those ready or intake issues, even when the blocker
lives outside
Todo or Triage.
- Non-done issues with the repo routing label that are missing configured
project, parent, kind, readiness, dependency, or body metadata only when they
are already in the configured ready or intake states.
- Issues from workflow script output whose tracker metadata needs repair before
Orchestrator can use them.
- Recently updated issues only when they are already in configured ready,
intake, or active tracker states.
For default mode, the main cleanup target is the configured ready state. If
config says that is Todo, make Todo the clean Orchestrator handoff queue.
If config treats Linear Backlog, icebox, someday, roadmap, or equivalent
states as parked/out-of-work-queue, skip them unless the user explicitly asks
for Linear Backlog review, Linear Backlog cleanup, or Linear Backlog backfill. If
the user says "backlog" generically, follow the repo config's backlog-grooming
scope instead of assuming the Linear Backlog status is in scope.
When building readiness-label queues such as ready-for-agent or
ready-for-human, exclude the configured done state up front unless the user
explicitly asks to audit Done cleanup.
Classify Issues
Classify each issue into exactly one primary outcome:
- ready for Orchestrator: one-PR
kind-slice, complete body contract, route,
labels, dependencies, and required estimate when configured
- blocked but shaped: otherwise ready, with dependency blockers encoded
- needs To Issues: container, spec, epic, vague plan, multi-PR work, missing
predicted footprint, or missing concrete scope split
- needs human decision: product, security, credential, customer, ADR, ownership,
priority, or acceptance-criteria decision required
- parked: intentionally not ready for agent work
- duplicate or likely duplicate
- orphan: missing route, project, parent, status, or owner metadata
- config gap: required tracker field or policy is missing from config
- Orchestrator action: script output shows active PR/check/review/status work
that belongs to Orchestrator
Do not infer scope by reading code or linked artifacts outside the workflow
scripts. If tracker text plus script output does not contain enough information
to classify safely, choose needs To Issues, needs human decision, or
config gap.
Cleanup
Apply obvious mechanical tracker updates:
- route orphan issues into the configured project, team, repo label, or parent
when tracker evidence is direct
- add missing configured labels for route, kind, type, risk, readiness, review
debt, and worker environment when policy allows
- set exactly one
kind-* value and clear conflicting kind labels
- keep
kind-spec and kind-epic as containers; never mark containers
ready-for-agent
- normalize issue bodies to the configured agent-ready headings
- preserve useful existing text and add missing headings without inventing facts
- add or preserve estimates only when config grants Issue Triage that authority
- encode dependency blockers from tracker relationships or issue text
- remove completed, canceled, duplicate, or unrelated blockers only when tracker
state makes that direct
- move complete issues from configured intake states to the configured ready
state during every normal triage run when the issue body is complete
- move complete
ready-for-agent kind-slice issues from explicitly requested
Linear Backlog cleanup/backfill scope to the configured ready state when
config grants promotion authority
- leave parked Linear Backlog or equivalent states alone unless explicitly in
scope
- move or label not-ready
Todo issues according to config: needs-info,
ready-for-human, configured intake, parked, or To Issues input. Do not leave
vague tickets in Todo with no next owner
- remove
ready-for-agent from vague, duplicate, parent, human-owned,
multi-outcome, boundary-incomplete, or body-incomplete issues
- mark implementation-ready slices
ready-for-agent when no further human
refinement is needed, even if dependency blockers remain
- reconcile stale tracker state only from tracker evidence or approved script
output, such as a linked PR merged, an active PR needing review state, a
changed PR head invalidating review evidence, or a terminal ticket retaining a
readiness label
- clear readiness labels when moving a ticket to the configured done state
- add, remove, or leave review evidence and human-merge labels only when script
output provides the current PR head, check, review, draft, and unresolved
thread state required by config
- add a concise tracker comment only when it helps a human or Orchestrator act
Do not close, cancel, reprioritize across projects, rewrite product scope, or
move active workflow states unless config or the user explicitly grants that
authority.
Do not manually verify linked PRs, branch state, CI, deploys, or code. Use only
tracker text and script output. If an issue appears to need verification that the
scripts did not provide, leave an Orchestrator next action such as "verify linked
PR is merged and update status if complete."
Readiness Contract
An issue can receive ready-for-agent only when it is:
- scoped to one PR
- scoped to one primary outcome
- assigned to the configured project, parent, or route
- labeled with one clear kind and required type/risk labels
- estimated when config requires estimates before handoff
- explicit about in-scope and out-of-scope work
- complete enough for Orchestrator to decide startability and dispatch
Required body content:
- outcome
- context docs or tracker links
- 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 scope fields must be concrete. In scope lists only the behavior, files,
docs, tests, and workflow state this PR may change. Out of scope lists
adjacent outcomes, sibling tickets, optional polish, broad refactors, production
actions, and follow-up behavior the worker must not deliver.
Populate likely files, packages, or artifacts only from existing tracker text,
config, To Issues output, or approved script output. Do not search the repo to
discover them. If they are missing, withhold ready-for-agent and leave the
issue for To Issues or human clarification.
If an issue carries ready-for-agent but the body says it is waiting on human
setup, credentials, provider decisions, security judgment, or a
ready-for-human rationale, treat the body as the stronger signal. Remove or
withhold ready-for-agent, preserve the exact human decision needed, and report
the contradiction.
Dependencies
Encode dependencies from bounded, authoritative evidence:
- explicit blocker text in the issue
- tracker parent, child, related, blocker, or duplicate relationships
- accepted sequencing in the scoped project's cited specs, roadmap, milestone,
or project docs
- concrete producer-before-consumer, schema-before-reader, API-before-client, or
release-order prerequisites stated by those sources
Use the smallest direct blocker graph that preserves the required order. Remove
terminal blockers when tracker state makes that safe, detect missing direct
edges and cycles, and keep transitive-only edges out unless the tracker requires
them. Do not inspect implementation code, PR diffs, branches, or deploy state to
invent ordering. If the tracker and cited source-of-truth docs still leave the
sequence ambiguous, leave the issue for To Issues or human clarification.
Dependency blockers do not remove ready-for-agent or worker-environment
labels. Encode dependency order with tracker relationships, blocker fields, or
the dependencies/body section so Orchestrator can compute startability.
When the frozen scope contains implementation kind-slice tickets, run the
dependency/startability script over the snapshot or a compact issue JSON:
node <skill-dir>/../ziw-orchestrate/scripts/linear-dag-start.mjs <snapshot-or-issues.json> --config <config.json>
Use the DAG result to fix the queue:
starts: leave in Todo with ready-for-agent; include in Orchestrator
handoff
frontier but not starts: repair missing labels, kind, ready state, active
claim, open-PR metadata, or body fields when safe
startableBlockers: convert each blocker into a ticket repair, a To Issues
action, a human question, or an Orchestrator next action
- cycles and out-of-scope blockers: encode the correct relationship if direct;
otherwise mark for human/To Issues
Human Clarification
Ask the user only when a safe tracker update depends on a concrete decision.
Keep questions short and tied to a specific issue.
If the user is unavailable or the run is non-interactive:
- add the configured human-input label or state
- add one concise tracker comment only when it helps the human answer
- include the exact question or next action in the final report
- leave the issue out of
ready-for-agent
Never fabricate scope, acceptance criteria, likely files, priority, estimates,
or dependency order to make a ticket look ready.
Guardrails
- Scripts first, no ad hoc exploration. Use approved workflow scripts and
tracker tools. Do not do manual code search, implementation file reads, tests,
one-off
gh queries, PR list spelunking, branch checks, CI checks, deploy
checks, production logs, alerts, security scans, package audits, or
repo-health sweeps.
- Do not implement code, create PRs, merge, deploy, or mutate production.
- Follow only cited source-of-truth project docs for scope and dependency
analysis. Do not follow PR, CI, deploy, log, or unrelated external links.
- Do not create noisy comments for small label edits.
- Do not create new label taxonomies unless config or the user explicitly names
them.
- Stop before destructive bulk changes if more than a small number of issues
would be canceled, closed, moved across projects, or reprioritized.
Done
Report:
- scripts run, script inputs, and any script fallback used
- tracker scope reviewed and whether the run was dry-run, partial, or applied
- Linear Backlog or intake states skipped or explicitly included
- issues changed, unchanged, parked, and needing human decision
- orphans routed or left with reasons
- labels, priorities, estimates, body contracts, dependency relationships, and
status recommendations updated
- ready-state issues made agent-ready or left with exact missing fields
- intake/review-debt issues promoted, left for To Issues, parked, or left for a
human decision
- issues ready for Orchestrator, blocked-but-ready, missing metadata, missing
body fields, duplicate, cyclic, or config-blocked
- stale tracker state repaired from script output, including Done/readiness,
review evidence, and human-merge label repairs
- exact Orchestrator next actions for any linked PR/status verification needed
- final
Todo handoff: starts, blocked-ready, and not-ready tickets removed or
marked with their exact next owner
- user questions asked or exact human next actions left
1---2name: ziw-triage-33description: Use for script-guided issue tracker triage when managing the current project backlog, making issues ready for Orchestrator by running workflow scripts, inspecting their outputs, and fixing labels, statuses, dependencies, body contracts, estimates, stale tracker state, and explicit human questions without ad hoc exploration.4argument-hint: "[project-url|team|repo|filter]"5metadata:6 source: https://skillmd.com/skills/zaks-io/ziw-triage-37---89# Issue Triage1011Issue Triage manages the issue tracker backlog so Orchestrator can run. It turns12tracker items into well-shaped, dependency-aware, agent-ready work or explicit13human/To Issues follow-up.1415The end state is a useful `Todo` backlog:1617- every `Todo` implementation ticket is a one-PR `kind-slice`18- ready work has `ready-for-agent`, the configured route, required labels,19 required estimate, complete body contract, and predicted footprint20- blocked ready work stays in `Todo` with blocker relationships encoded21- not-ready work is labeled or moved to the configured human, intake, parked, or22 To Issues path when config grants that authority23- Orchestrator can consume the final `starts`, blocked-ready list, and next24 actions without re-triaging the same queue2526Default triage starts from the configured ready and intake states plus direct27blockers only. In most Linear repos this means `Todo`, `Triage`, and any active28issues that directly block those tickets. Do not include unrelated Linear29`Backlog`, Duplicate, Done, canceled, icebox, or other parked/terminal states by30default.3132This skill is script-driven tracker grooming. It is not research,33implementation, code review, repo health monitoring, CI diagnosis, deploy34diagnosis, security scanning, or production triage.3536Read only:3738- `docs/agents/workflow/config.md`39- source-of-truth specs, roadmap, milestone, and project docs cited by the40 config or scoped tickets41- issue tracker metadata, bodies, comments, labels, statuses, estimates,42 projects, parents, and relationships43- explicit user instructions44- approved workflow script outputs from `skills/ziw-orchestrate/scripts`4546Run the scripts, read the output, inspect only the bounded tracker scope and its47cited source-of-truth docs, then fix the tickets. The scripts are the observation48layer for queue, PR, and worker state; the agent does not rediscover that state49manually. No manual code search, implementation file reads, one-off `gh`50queries, CI spelunking, deploy checks, log review, security tool runs, or broad51repo health checks. If handoff quality depends on information that is not in the52tracker, config, cited source-of-truth docs, or script output, leave the exact53missing field for To Issues or a human.5455Tracker/MCP tools are for applying ticket mutations and reading specific ticket56fields that the scripts do not return. Do not use MCP calls to rebuild the same57inventory, PR state, dependency frontier, or readiness decisions that the scripts58already compute.5960## Inputs6162- Issue tracker project, team, repo label, board, roadmap, query, filter, or63 explicit Linear `Backlog` state scope.64- Repo path and `docs/agents/workflow/config.md`.65- Existing tracker statuses, labels, priorities, estimates, dependencies,66 parents, children, duplicates, issue bodies, and comments.67- Optional user instructions for dry run, first-run intake backfill, first-run68 Linear Backlog backfill, Linear Backlog review, intake cleanup, priority69 policy, or orphan routing.7071## Context7273Read `docs/agents/workflow/config.md` first. If it is missing, run or request74`ziw-setup` before broad cleanup.7576Confirm these config values before mutating the issue tracker:7778- provider location, project, team, roadmap, and routing label79- status names and mappings80- ready state, intake states, active states, done state, and Linear Backlog81 policy82- readiness, type, risk, review-debt, worker environment, and route labels83- readiness label policy and startable work criteria84- priority policy, estimate policy, dependency policy, and orphan policy85- agent-ready issue body contract86- Issue Triage mutation authority87- dependency graph mechanism and blocker relationship direction8889If tracker metadata disagrees with config, update only exact label gaps that are90safe to create. Do not create or rename workflows, statuses, teams, projects,91boards, roadmaps, or label taxonomies without explicit approval.9293## Operating Loop9495Start each run by choosing one mode:9697- default backlog grooming98- explicit issue, project, board, repo label, team, query, or filter99- requested Linear Backlog or intake cleanup100- dry run101102A normal `ziw-triage` invocation is a request to process the configured intake103states. Complete implementation-ready intake tickets move from `Triage` to the104configured ready state, usually `Todo`, without requiring the user to separately105say "intake cleanup." Linear `Backlog` remains excluded unless explicitly106requested. A dry run recommends the same transitions without applying them.107108Then follow this order:1091101. State the bounded tracker scope, skipped states, allowed mutations, and111 ready/Done rules from config.1122. Run the configured workflow scripts before broad tracker reads:113 `../ziw-orchestrate/scripts/tick-snapshot.mjs` for the compact queue snapshot,114 `../ziw-orchestrate/scripts/tick-plan.mjs` for deterministic queue decisions,115 and `../ziw-orchestrate/scripts/linear-dag-start.mjs` for116 dependency/startability. In default mode, pass the configured ready and intake117 states to `tick-snapshot.mjs`, usually `--linear-states Todo,Triage`, so the118 script returns only those states plus their direct blockers. If a script cannot119 run because credentials or inputs are missing, report the exact missing input120 and use tracker tools only for the smallest bounded replacement query.1213. Build the issue set from script output and tracker queries. Read cited122 source-of-truth docs when needed to verify scope or dependency order.1234. Freeze the issue set. Do not expand it because a linked PR, branch, CI run,124 deploy, alert, or code path looks interesting.1255. Classify every issue.1266. Apply safe tracker updates in batches.1277. Re-run the DAG/startability script over the updated issue set when128 implementation `kind-slice` issues are in scope.1298. Report what changed, what remains blocked, and exactly what Orchestrator,130 To Issues, or a human should do next.131132If the issue set is empty, report the empty scoped result and stop.133134## Decision Routine135136Use script and tracker output to choose one action per issue:137138- **Fix now**: safe label, status, body, estimate, route, dependency, stale139 readiness, review-evidence, or handoff-field repair is clear.140- **Ready for Orchestrator**: the issue is a one-PR `kind-slice` with body,141 route, readiness, required estimate, dependency encoding, and predicted142 footprint.143- **Blocked but shaped**: the issue is otherwise ready, but144 `linear-dag-start.mjs` reports dependency blockers.145- **Needs To Issues**: the issue is a container, vague plan, multi-PR scope,146 missing split, or missing predicted footprint.147- **Needs human**: product, security, credential, customer, ADR, ownership,148 priority, or acceptance-criteria decision is missing.149- **Orchestrator action**: script output shows linked PR/status/check/review150 state needs active workflow handling that triage should not perform.151- **Park**: the tracker state is intentionally outside the current work queue.152153Do not invent a new investigation path. If the next action is not one of these,154record a config gap or ask a specific human question.155156Use the script outputs directly:157158- `tick-snapshot.mjs` gives the compact queue, linked PR footprint, current heads,159 checks, review state, and Linear queue metadata when credentials are available.160- `tick-plan.mjs` gives ready-state promotions, review-evidence actions,161 human-merge label actions, capacity/dispatch signals, and the deterministic162 next workflow action.163- `linear-dag-start.mjs` gives roots, frontier, starts, blockers, cycles, and164 missing startability requirements.165166Triage owns ticket repairs implied by those outputs. Orchestrator owns active167delivery actions implied by those outputs.168169## Default Scope170171Default triage is `Todo` plus intake grooming in the tracker. Build the default172issue set from configured tracker state and script output, not from ad hoc173exploration:1741751. Issues in the configured ready state, usually `Todo`.1762. Issues in configured intake or review-debt intake states that config says177 Issue Triage should normalize, usually `Triage`.1783. Direct active blockers of those ready or intake issues, even when the blocker179 lives outside `Todo` or `Triage`.1804. Non-done issues with the repo routing label that are missing configured181 project, parent, kind, readiness, dependency, or body metadata only when they182 are already in the configured ready or intake states.1835. Issues from workflow script output whose tracker metadata needs repair before184 Orchestrator can use them.1856. Recently updated issues only when they are already in configured ready,186 intake, or active tracker states.187188For default mode, the main cleanup target is the configured ready state. If189config says that is `Todo`, make `Todo` the clean Orchestrator handoff queue.190191If config treats Linear `Backlog`, icebox, someday, roadmap, or equivalent192states as parked/out-of-work-queue, skip them unless the user explicitly asks193for Linear Backlog review, Linear Backlog cleanup, or Linear Backlog backfill. If194the user says "backlog" generically, follow the repo config's backlog-grooming195scope instead of assuming the Linear `Backlog` status is in scope.196197When building readiness-label queues such as `ready-for-agent` or198`ready-for-human`, exclude the configured done state up front unless the user199explicitly asks to audit Done cleanup.200201## Classify Issues202203Classify each issue into exactly one primary outcome:204205- ready for Orchestrator: one-PR `kind-slice`, complete body contract, route,206 labels, dependencies, and required estimate when configured207- blocked but shaped: otherwise ready, with dependency blockers encoded208- needs To Issues: container, spec, epic, vague plan, multi-PR work, missing209 predicted footprint, or missing concrete scope split210- needs human decision: product, security, credential, customer, ADR, ownership,211 priority, or acceptance-criteria decision required212- parked: intentionally not ready for agent work213- duplicate or likely duplicate214- orphan: missing route, project, parent, status, or owner metadata215- config gap: required tracker field or policy is missing from config216- Orchestrator action: script output shows active PR/check/review/status work217 that belongs to Orchestrator218219Do not infer scope by reading code or linked artifacts outside the workflow220scripts. If tracker text plus script output does not contain enough information221to classify safely, choose `needs To Issues`, `needs human decision`, or222`config gap`.223224## Cleanup225226Apply obvious mechanical tracker updates:227228- route orphan issues into the configured project, team, repo label, or parent229 when tracker evidence is direct230- add missing configured labels for route, kind, type, risk, readiness, review231 debt, and worker environment when policy allows232- set exactly one `kind-*` value and clear conflicting kind labels233- keep `kind-spec` and `kind-epic` as containers; never mark containers234 `ready-for-agent`235- normalize issue bodies to the configured agent-ready headings236- preserve useful existing text and add missing headings without inventing facts237- add or preserve estimates only when config grants Issue Triage that authority238- encode dependency blockers from tracker relationships or issue text239- remove completed, canceled, duplicate, or unrelated blockers only when tracker240 state makes that direct241- move complete issues from configured intake states to the configured ready242 state during every normal triage run when the issue body is complete243- move complete `ready-for-agent` `kind-slice` issues from explicitly requested244 Linear Backlog cleanup/backfill scope to the configured ready state when245 config grants promotion authority246- leave parked Linear Backlog or equivalent states alone unless explicitly in247 scope248- move or label not-ready `Todo` issues according to config: `needs-info`,249 `ready-for-human`, configured intake, parked, or To Issues input. Do not leave250 vague tickets in `Todo` with no next owner251- remove `ready-for-agent` from vague, duplicate, parent, human-owned,252 multi-outcome, boundary-incomplete, or body-incomplete issues253- mark implementation-ready slices `ready-for-agent` when no further human254 refinement is needed, even if dependency blockers remain255- reconcile stale tracker state only from tracker evidence or approved script256 output, such as a linked PR merged, an active PR needing review state, a257 changed PR head invalidating review evidence, or a terminal ticket retaining a258 readiness label259- clear readiness labels when moving a ticket to the configured done state260- add, remove, or leave review evidence and human-merge labels only when script261 output provides the current PR head, check, review, draft, and unresolved262 thread state required by config263- add a concise tracker comment only when it helps a human or Orchestrator act264265Do not close, cancel, reprioritize across projects, rewrite product scope, or266move active workflow states unless config or the user explicitly grants that267authority.268269Do not manually verify linked PRs, branch state, CI, deploys, or code. Use only270tracker text and script output. If an issue appears to need verification that the271scripts did not provide, leave an Orchestrator next action such as "verify linked272PR is merged and update status if complete."273274## Readiness Contract275276An issue can receive `ready-for-agent` only when it is:277278- scoped to one PR279- scoped to one primary outcome280- assigned to the configured project, parent, or route281- labeled with one clear kind and required type/risk labels282- estimated when config requires estimates before handoff283- explicit about in-scope and out-of-scope work284- complete enough for Orchestrator to decide startability and dispatch285286Required body content:287288- outcome289- context docs or tracker links290- likely files, packages, or artifacts291- in scope292- out of scope293- acceptance criteria294- required checks295- security, privacy, data, and operational invariants296- dependencies or blockers297- estimate when config stores estimates in the body298299The scope fields must be concrete. `In scope` lists only the behavior, files,300docs, tests, and workflow state this PR may change. `Out of scope` lists301adjacent outcomes, sibling tickets, optional polish, broad refactors, production302actions, and follow-up behavior the worker must not deliver.303304Populate likely files, packages, or artifacts only from existing tracker text,305config, To Issues output, or approved script output. Do not search the repo to306discover them. If they are missing, withhold `ready-for-agent` and leave the307issue for To Issues or human clarification.308309If an issue carries `ready-for-agent` but the body says it is waiting on human310setup, credentials, provider decisions, security judgment, or a311`ready-for-human` rationale, treat the body as the stronger signal. Remove or312withhold `ready-for-agent`, preserve the exact human decision needed, and report313the contradiction.314315## Dependencies316317Encode dependencies from bounded, authoritative evidence:318319- explicit blocker text in the issue320- tracker parent, child, related, blocker, or duplicate relationships321- accepted sequencing in the scoped project's cited specs, roadmap, milestone,322 or project docs323- concrete producer-before-consumer, schema-before-reader, API-before-client, or324 release-order prerequisites stated by those sources325326Use the smallest direct blocker graph that preserves the required order. Remove327terminal blockers when tracker state makes that safe, detect missing direct328edges and cycles, and keep transitive-only edges out unless the tracker requires329them. Do not inspect implementation code, PR diffs, branches, or deploy state to330invent ordering. If the tracker and cited source-of-truth docs still leave the331sequence ambiguous, leave the issue for To Issues or human clarification.332333Dependency blockers do not remove `ready-for-agent` or worker-environment334labels. Encode dependency order with tracker relationships, blocker fields, or335the dependencies/body section so Orchestrator can compute startability.336337When the frozen scope contains implementation `kind-slice` tickets, run the338dependency/startability script over the snapshot or a compact issue JSON:339340```sh341node <skill-dir>/../ziw-orchestrate/scripts/linear-dag-start.mjs <snapshot-or-issues.json> --config <config.json>342```343344Use the DAG result to fix the queue:345346- `starts`: leave in `Todo` with `ready-for-agent`; include in Orchestrator347 handoff348- `frontier` but not `starts`: repair missing labels, kind, ready state, active349 claim, open-PR metadata, or body fields when safe350- `startableBlockers`: convert each blocker into a ticket repair, a To Issues351 action, a human question, or an Orchestrator next action352- cycles and out-of-scope blockers: encode the correct relationship if direct;353 otherwise mark for human/To Issues354355## Human Clarification356357Ask the user only when a safe tracker update depends on a concrete decision.358Keep questions short and tied to a specific issue.359360If the user is unavailable or the run is non-interactive:361362- add the configured human-input label or state363- add one concise tracker comment only when it helps the human answer364- include the exact question or next action in the final report365- leave the issue out of `ready-for-agent`366367Never fabricate scope, acceptance criteria, likely files, priority, estimates,368or dependency order to make a ticket look ready.369370## Guardrails371372- Scripts first, no ad hoc exploration. Use approved workflow scripts and373 tracker tools. Do not do manual code search, implementation file reads, tests,374 one-off `gh` queries, PR list spelunking, branch checks, CI checks, deploy375 checks, production logs, alerts, security scans, package audits, or376 repo-health sweeps.377- Do not implement code, create PRs, merge, deploy, or mutate production.378- Follow only cited source-of-truth project docs for scope and dependency379 analysis. Do not follow PR, CI, deploy, log, or unrelated external links.380- Do not create noisy comments for small label edits.381- Do not create new label taxonomies unless config or the user explicitly names382 them.383- Stop before destructive bulk changes if more than a small number of issues384 would be canceled, closed, moved across projects, or reprioritized.385386## Done387388Report:389390- scripts run, script inputs, and any script fallback used391- tracker scope reviewed and whether the run was dry-run, partial, or applied392- Linear Backlog or intake states skipped or explicitly included393- issues changed, unchanged, parked, and needing human decision394- orphans routed or left with reasons395- labels, priorities, estimates, body contracts, dependency relationships, and396 status recommendations updated397- ready-state issues made agent-ready or left with exact missing fields398- intake/review-debt issues promoted, left for To Issues, parked, or left for a399 human decision400- issues ready for Orchestrator, blocked-but-ready, missing metadata, missing401 body fields, duplicate, cyclic, or config-blocked402- stale tracker state repaired from script output, including Done/readiness,403 review evidence, and human-merge label repairs404- exact Orchestrator next actions for any linked PR/status verification needed405- final `Todo` handoff: starts, blocked-ready, and not-ready tickets removed or406 marked with their exact next owner407- user questions asked or exact human next actions left