---
name: deliver-tracking-issue
description:
  Deliver an existing plan-tracking GitHub issue end to end by resuming issue-backed execution, requiring specialist review and repair for
  every PR, merging completed PRs, updating issue-hosted execution state, and closing through tracking-issue-closeout.
---

# Deliver Tracking Issue

Use this workflow when the user wants an existing lightweight plan-tracking issue carried through implementation, reviewed PR delivery, and
final issue closure.

## Contract

Prereqs:

- Run inside the target GitHub-backed git repository.
- `git`, `gh`, `python3`, and project validation tools are available on `PATH`.
- `gh auth status` succeeds before live GitHub issue or PR reads/writes.
- The target issue was created by `plan-tracking-issue` or has equivalent source and plan snapshot comments.
- The issue follows the lightweight plan-tracking contract, not a `plan-issue` dispatch runtime with subagent-owned task lanes.
- Required project preflight passes before repository edits.
- Invoking this workflow is explicit authorization to deliver and close the issue unless the user supplies a narrower stop condition.

Inputs:

- GitHub issue number or URL.
- Optional repository override (`--repo <owner/repo>`) when the local remote is ambiguous.
- Optional target selector: whole issue/plan, sprint, task id, phase, priority, or resume from latest incomplete task.
- Optional PR kind (`feature` or `bug`) for PR delivery skills; default to `feature` unless the issue is clearly a bug fix.
- Optional base branch; default to the repository default branch resolved through `gh repo view`.
- Optional close approval URL for `tracking-issue-closeout --review-comment-url`; otherwise pass `--review-approved` because this workflow
  request is the closure approval.
- Optional `--allow-no-checks`, `--keep-branch`, or `--no-cleanup` only when explicitly requested by the user or project policy.
- Optional stop condition, such as stop after first PR, stop before merge, or stop before closeout.

Outputs:

- Completed implementation for all selected issue tasks, with scoped code, docs, config, tests, or workflow changes.
- One or more PRs opened, checked, specialist-reviewed through the shared
  delivery gate, repaired, revalidated, merged, and cleaned up unless a stop condition blocks delivery.
- For every PR, a `code-review-specialists` review pass with at least `testing`
  and `maintainability` forced by the shared delivery specialist review gate, even for small diffs.
- Issue-hosted `execute-from-tracking-issue:state:v1`, `session:v1`, and `validation:v1` comments updated after task execution, PR review,
  PR merge, and final completion.
- For every PR, a provider-side delivery review outcome comment URL recorded in
  issue-hosted session or validation evidence.
- Runtime findings recorded with a disposition: fixed now, accepted residual risk, linked follow-up, deferred task, stop for confirmation, or
  no action needed.
- Final lifecycle completion gate passing through `execute-from-tracking-issue/scripts/tracking-issue-lifecycle.sh --dry-run --require-complete`.
- Final issue close through `tracking-issue-closeout`, including dashboard repair, closeout comment, and issue close.
- A concise final response with issue URL, merged PRs, validation, specialist review outcome, closeout result, and any caveats.

Exit codes:

- `0`: all selected tasks are complete, PRs are merged, closeout succeeds, and the issue is closed.
- `1`: workflow blocked or failed because execution, validation, review repair, PR merge, lifecycle completion, or closeout failed.
- `2`: usage error or missing required input.

Failure modes:

- Target issue is unreadable, closed unexpectedly, not associated with the selected repository, or missing required plan-tracking markers.
- The issue is a dispatch/`plan-issue` runtime; use `dispatch-plan-delivery` or `dispatch-issue-closeout` instead.
- Required task, acceptance criteria, validation, branch, or reversibility constraints are too ambiguous to execute safely.
- Implementation discovers a material mismatch with the source/plan snapshots, architecture assumptions, acceptance criteria, or safety model
  that needs user confirmation before scope changes.
- A non-blocking runtime finding is left without an issue-visible disposition, evidence anchor, or follow-up decision.
- Work tree contains unrelated dirty changes that overlap the selected task or PR repair scope.
- `code-review-specialists` reports concrete findings that cannot be repaired within the selected issue scope.
- Required checks fail, are pending too long, are missing without explicit `--allow-no-checks`, or cannot be repaired.
- A PR would auto-close the tracking issue before `tracking-issue-closeout` unless lifecycle completion has already passed.
- Latest issue-hosted execution state cannot be made `complete`, all task rows cannot be set to `done` or `deferred`, or validation/PR
  evidence is missing.
- `tracking-issue-closeout` close gates fail, including missing approval, missing validation evidence, unmerged linked PRs, or GitHub mutation
  failure.

## Entrypoint

- None. This is a scriptless orchestration workflow that composes existing deterministic helpers and workflow skills.

Primary composed entrypoints:

- `$AGENT_HOME/skills/workflows/issue/execute-from-tracking-issue/scripts/tracking-issue-lifecycle.sh`
- `$AGENT_HOME/skills/workflows/code-review/code-review-specialists/scripts/review_specialists.py`
- `$AGENT_HOME/skills/workflows/pr/github/deliver-github-pr/scripts/deliver-github-pr.sh`
- `$AGENT_HOME/skills/workflows/pr/github/close-github-pr/scripts/close-github-pr.sh`
- `$AGENT_HOME/skills/workflows/issue/tracking-issue-closeout/scripts/tracking-issue-closeout.sh`

## Boundary

- This workflow may implement and repair code within the selected tracking-issue scope.
- `code-review-specialists` remains read-only. Review findings are repaired by this workflow on the PR branch, followed by validation and a
  fresh review pass.
- Provider delivery skills own the common mandatory PR review gate through
  `skills/workflows/_shared/references/DELIVERY_SPECIALIST_REVIEW_GATE.md`;
  this workflow adds issue-visible evidence, runtime-finding disposition, lifecycle completion, and closeout requirements.
- Provider delivery skills also own provider-side review outcome comments through
  `skills/workflows/_shared/references/DELIVERY_REVIEW_OUTCOME_COMMENT.md`;
  this workflow records the comment URL in issue evidence without duplicating
  the full report.
- `tracking-issue-closeout` remains the final closeout lane only. It must not create execution state or repair incomplete task ledgers.
- Do not use this workflow for heavyweight dispatch issues with task-lane owners, sprint acceptance, or `plan-issue` close gates.
- Do not spawn subagents unless the user separately invokes a delegation mode such as `parallel-first` or `orchestrator-first`.

## Workflow

1. Resolve context and issue state:
   - Run project-required preflight.
   - Resolve repository, default branch, issue number, issue URL, and close policy.
   - Run:

     ```bash
     $AGENT_HOME/skills/workflows/issue/execute-from-tracking-issue/scripts/tracking-issue-lifecycle.sh \
       --issue <number-or-url> --repo <owner/repo> --dry-run --report-out <path>
     ```

   - Confirm source snapshot, plan snapshot, latest execution state, session, validation evidence, dashboard links, linked PRs, blockers, and
     latest incomplete task.
   - If the issue contains `plan-issue` runtime rows or subagent task-lane ownership, stop and route to dispatch workflows.

2. Execute the next issue-backed task:
   - Use `execute-from-tracking-issue` as the execution-state owner.
   - Prefer issue-hosted source and plan snapshots over local files.
   - Classify runtime findings through the Runtime Findings And Follow-Up Policy before continuing to the next task or PR close.
   - For production behavior changes, capture failing-test evidence or record an explicit waiver in the issue state before editing production
     behavior.
   - Preserve unrelated dirty work.
   - Open a PR for completed implementation scope by default; use `Refs #<issue>` rather than `Closes #<issue>` in PR bodies so closeout owns
     final issue closure.

3. Deliver each PR:
   - Resolve PR metadata:

     ```bash
     gh pr view <pr> --json number,url,baseRefName,headRefName,isDraft,state,statusCheckRollup,closingIssuesReferences
     ```

   - Wait for required checks through `deliver-github-pr wait-checks` or the equivalent provider-scoped delivery gate.
   - Missing checks block unless the user explicitly supplied `--allow-no-checks`; failed, skipped required, blocked, or pending checks must
     be repaired.

4. Run mandatory specialist review for every PR:
   - Follow the shared delivery specialist review gate:
     `skills/workflows/_shared/references/DELIVERY_SPECIALIST_REVIEW_GATE.md`.
   - Always run deterministic scope detection with the shared forced minimum
     lenses:

     ```bash
     $AGENT_HOME/skills/workflows/code-review/code-review-specialists/scripts/review_specialists.py \
       scope --base <pr-base-ref> --testing --maintainability
     ```

   - This forced minimum applies even when `diff_lines < 50`; broader lens
     selection comes from the shared gate.

5. Classify and repair review findings:
   - Treat evidence-backed concrete findings as blocking.
   - Repair concrete findings on the same PR branch when they are inside the selected issue scope.
   - After repairs, rerun focused validation, required checks, and the affected specialist lenses.
   - Classify residual risks, weakly evidenced concerns, intentionally accepted tradeoffs, and cleanup notes through the Runtime Findings And
     Follow-Up Policy.
   - Repeat review and repair until there are no concrete unresolved findings, no undisposed runtime findings, or the workflow is genuinely
     blocked.

6. Merge PRs and update issue evidence:
   - Before merge, run the lifecycle helper with `--dry-run --require-complete` when the PR would close or materially complete the tracking
     issue.
   - Use `close-github-pr` or `deliver-github-pr close` for merge, draft readiness, required checks, and branch cleanup.
   - After each merge, append or update issue-backed session/validation evidence with:
     - merged PR number and URL
     - delivery review outcome comment URL
     - review lenses used
     - findings repaired or accepted residual risks
     - follow-up issues, deferred task rows, or no-action decisions for non-blocking findings
     - validation commands and results
     - updated task ledger status
   - Re-run lifecycle dry-run after dashboard or state updates and repair stale dashboard links when needed.

7. Repeat until the issue is complete:
   - Continue selecting the next incomplete task from the latest issue-hosted execution state.
   - Re-check runtime findings before each new task and before final completion.
   - If all task rows are `done` or explicitly `deferred`, post the final session/validation evidence and set latest state to `complete`.
   - Run:

     ```bash
     $AGENT_HOME/skills/workflows/issue/execute-from-tracking-issue/scripts/tracking-issue-lifecycle.sh \
       --issue <number-or-url> --repo <owner/repo> --dry-run --require-complete
     ```

8. Close the tracking issue:
   - Normal open issue:

     ```bash
     $AGENT_HOME/skills/workflows/issue/tracking-issue-closeout/scripts/tracking-issue-closeout.sh \
       --issue <number-or-url> --repo <owner/repo> --review-approved
     ```

   - If a PR already closed the issue before closeout, run repair/finalize mode instead:

     ```bash
     $AGENT_HOME/skills/workflows/issue/tracking-issue-closeout/scripts/tracking-issue-closeout.sh \
       --issue <number-or-url> --repo <owner/repo> --review-approved --repair-closed --finalize-closed
     ```

   - If the user supplied a close approval comment, use `--review-comment-url <url>` instead of `--review-approved`.

## Small PR Review Policy

- Small PR specialist selection is inherited from the shared delivery specialist
  review gate. Every PR must still run the forced `testing` and
  `maintainability` minimum, and must not skip only because the diff is small.
- Tracking-issue delivery adds an issue-visible requirement: record the lenses
  used, delivery review outcome comment URL, concrete findings repaired,
  accepted residual risks, follow-up links, deferred task rows, or explicit
  `no-action` decisions in session or validation evidence before closeout.

## Runtime Findings And Follow-Up Policy

Classify every meaningful runtime finding before continuing the delivery loop. A runtime finding is anything discovered during code reading,
implementation, validation, specialist review, PR checks, merge prep, or closeout prep that materially informs the task outcome.

Use these dispositions:

- `stop-for-confirmation`: the finding changes accepted intent, scope, safety, data, architecture, or workflow family. Stop before further
  implementation, merge, or closeout.
- `fix-now`: the finding is concrete, in scope, and should be repaired on the current branch or PR before merge.
- `accepted-residual`: the finding is real but intentionally accepted for this delivery because it is low risk, already covered by validation,
  or outside the current issue's done criteria.
- `follow-up-linked`: the finding is actionable but outside the current delivery. Create or link a follow-up issue before closeout unless a
  project policy says deferred task rows are the durable follow-up surface.
- `deferred-task`: the finding maps to a task row that should remain explicitly `deferred` with evidence and rationale in the latest
  execution-state ledger.
- `no-action`: the finding is a checked observation with no required change or follow-up.

Stop for confirmation when:

- The planned file, API, command, schema, migration, deployment surface, or runtime boundary does not exist or behaves differently.
- The plan's acceptance criteria are impossible, unsafe, obsolete, or contradict current project rules.
- Continuing requires broader scope, destructive migration, user-visible behavior change, or compatibility break not represented in the plan.
- The discovered design would route the work to a different workflow family, such as dispatch task-lane orchestration.
- Fixing the issue safely requires a product, security, data, or operational decision the plan did not settle.

For `stop-for-confirmation`:

- Do not silently rewrite the plan, widen scope, defer tasks, or substitute a different design just to keep the delivery loop moving.
- Leave the GitHub issue open.
- Add an `execute-from-tracking-issue:session:v1` or `validation:v1` comment with:
  - known facts and evidence
  - the exact source/plan mismatch
  - why continuing would change intent, risk, or scope
  - viable options, including continue with amended scope, defer/create follow-up, or stop/replan
  - the specific confirmation needed from the user
- Resume delivery only after the user or project policy confirms the amended scope or stop decision.

For non-blocking findings:

- Keep moving only after recording the finding in the next issue-hosted session or validation comment.
- Record enough detail for a later reader to understand the decision without chat history:
  - finding summary
  - evidence anchor, such as file path, command output summary, PR URL, check name, or specialist lens
  - disposition
  - rationale for continuing
  - follow-up link, deferred task row, or explicit `no-action` decision
- Minor implementation details that preserve the accepted design intent may continue without confirmation, but still record them when they
  affect future maintainability, review context, operations, or user-visible behavior.
- Accepted residual risks must be low enough that the issue can honestly close as completed. If the item remains actionable after this
  delivery, use `follow-up-linked` or `deferred-task` instead of `accepted-residual`.
- Before closeout, the final session or validation evidence must include a compact residual/follow-up summary. Closeout must not proceed while
  any meaningful runtime finding lacks a disposition.

## Completion Gate

- Successful completion means:
  - latest issue-hosted execution state is `complete`
  - every task row is `done` or explicitly `deferred`
  - every PR linked from execution evidence is merged or intentionally excluded with evidence
  - every PR has a specialist review result and any concrete findings are repaired
  - every PR has a provider-side delivery review outcome comment URL recorded
    in issue evidence
  - every meaningful runtime finding has an issue-visible disposition and any actionable follow-up is linked or deferred
  - required checks and local validation are green or explicitly accepted under project policy
  - `tracking-issue-closeout` succeeds and the issue is closed or repair-finalized
- Do not report success while the next action is still to run checks, repair review findings, merge a PR, update issue state, or close the
  issue.
- If blocked, leave the issue open with an exact unblock action in an `execute-from-tracking-issue:session:v1` or `validation:v1` comment.

## Relationship To Nearby Skills

- `plan-tracking-issue`: creates or prepares the tracking issue and source/plan snapshots.
- `execute-from-tracking-issue`: owns issue-backed execution state and append-only execution/session/validation comments.
- `code-review-specialists`: supplies read-only specialist review; this workflow repairs findings outside that skill.
- `deliver-github-pr` and `close-github-pr`: own provider-specific PR checks, merge, and branch cleanup.
- Shared delivery specialist review gate:
  `skills/workflows/_shared/references/DELIVERY_SPECIALIST_REVIEW_GATE.md`
- Shared delivery review outcome comment:
  `skills/workflows/_shared/references/DELIVERY_REVIEW_OUTCOME_COMMENT.md`
- `tracking-issue-closeout`: owns final dashboard repair, closeout comment, and issue closure.
- `dispatch-plan-delivery` / `dispatch-issue-closeout`: use these instead when the issue is a heavyweight dispatch runtime.
