deliver-tracking-issue

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 deliver-dispatch-plan 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.
• Provider delivery and issue evidence use the shared disposition schema: skills/workflows/_shared/references/DELIVERY_REVIEW_OUTCOME_SCHEMA.md.
• 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:

     $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:

     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:

     $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:

     $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:

     $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:

     $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.
• deliver-dispatch-plan / dispatch-issue-closeout: use these instead when the issue is a heavyweight dispatch runtime.