execute-from-tracking-issue

name	execute-from-tracking-issue
description	Resume and execute implementation work from a plan-tracking GitHub issue that carries issue-hosted source, plan, and execution-state snapshots, preserving progress on the issue when local docs/plans files may be cleaned up.

Execute From Tracking Issue

Execute a plan-tracking GitHub issue as the durable source of truth when local plan files are optional or already gone.

Contract

Prereqs:

• Run inside the target GitHub-backed git repository.
• gh is available on PATH, and gh auth status succeeds.
• Target issue number or URL is known.
• The issue was created or prepared by plan-tracking-issue, or it contains equivalent snapshot comments with stable markers.
• Issue-hosted source and plan snapshots are present, or the local source/plan files still exist and can be snapshotted before execution.
• Required project preflight passes before repo edits.

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 explicit stop condition.
• Optional local source, plan, or execution-state path only as a recovery fallback when the issue lacks snapshots.
• Optional branch, PR, validation, commit, delivery, and close-policy constraints from the user or project rules.

Outputs:

• Scoped code, docs, config, test, or workflow changes for the selected issue-backed plan scope.
• A feature branch, semantic commit, pushed branch, and PR for completed implementation scope by default unless the user requests local-only work, direct push, or project policy says otherwise.
• Issue body updated as the current dashboard: status, target scope, current task, next task, validation summary, linked PR/commit, and blockers.
• Append-only issue comments for source snapshot, plan snapshot, execution-state updates, session logs, validation evidence, blockers, and final summary.
• Optional execute-from-tracking-issue.lifecycle-report.v1 JSON audit report, rendered dashboard body, and body-only dashboard repair through the deterministic lifecycle helper.
• Local execution-state file only when needed as a working scratchpad; GitHub issue comments remain the durable record.
• A concise final response with changed files, validation, issue URL, current status, and next action.

Exit codes:

• 0: lifecycle helper succeeded, or the workflow completed the selected scope.
• 1: lifecycle helper found blocking drift / missing markers, a requested completion gate failed, or a workflow command failed.
• 2: lifecycle helper usage error.

Failure modes:

• Target issue is missing, closed unexpectedly, unreadable, or not associated with the current repository.
• Issue lacks source/plan snapshots and local source/plan files are also unavailable.
• Snapshot markers are duplicated, malformed, or contradict local files in a way that changes scope or acceptance criteria.
• Issue current-state dashboard conflicts with append-only execution comments.
• Latest execute-from-tracking-issue:state:v1 comment does not use the canonical ID | Status | Task | Evidence | Notes task ledger.
• A requested completion gate fails because latest state is not complete, a task row is not done or deferred, validation or PR evidence is missing, or the issue dashboard does not link the latest state/session/validation comments.
• Required task, acceptance criteria, validation, branch, or reversibility constraints are too ambiguous to execute safely.
• Work tree contains unrelated dirty changes that overlap the selected task.
• Validation fails and cannot be fixed within the selected issue scope.
• GitHub comment/body mutation fails, so durable execution state cannot be persisted.
• Body-only dashboard repair fails, or repair is attempted against an issue that does not pass marker and state-schema audit.

Entrypoint

• $AGENT_HOME/skills/workflows/issue/execute-from-tracking-issue/scripts/tracking-issue-lifecycle.sh

Relative entrypoint path: scripts/tracking-issue-lifecycle.sh.

Use this deterministic helper to audit marker presence, validate the canonical state ledger, render the current dashboard, detect stale dashboard links, and optionally repair only the mutable issue body. The helper does not post append-only state, session, validation, or closeout comments.

Common helper commands:

tracking-issue-lifecycle.sh --issue <number-or-url> --repo <owner/repo> --dry-run --body-out /tmp/dashboard.md --report-out /tmp/report.json
tracking-issue-lifecycle.sh --issue <number-or-url> --repo <owner/repo> --repair-body --body-out /tmp/dashboard.md --report-out /tmp/report.json
tracking-issue-lifecycle.sh --issue <number-or-url> --repo <owner/repo> --dry-run --require-complete --report-out /tmp/report.json

--require-complete is the pre-merge/pre-close gate. It requires the latest state status to be complete, every task row to be done or deferred, linked validation and PR evidence, and current dashboard links.

Issue Snapshot Contract

Use these marker lines so future sessions can recover without local docs/plans/ files:

• <!-- plan-tracking-issue:snapshot:v1 kind=source -->
• <!-- plan-tracking-issue:snapshot:v1 kind=plan -->
• <!-- execute-from-tracking-issue:state:v1 -->
• <!-- execute-from-tracking-issue:session:v1 -->
• <!-- execute-from-tracking-issue:validation:v1 -->

Issue body is the mutable dashboard. Snapshot, state, session, validation, and final-summary comments are append-only evidence. Do not rely on chat history or local plan paths as the only durable execution record once this skill starts.

The canonical state ledger columns are exactly ID | Status | Task | Evidence | Notes. Local execution-state Markdown is a scratchpad or recovery input after issue-backed execution starts; the latest issue-hosted execute-from-tracking-issue:state:v1 comment is authoritative.

Snapshot and execution-state comments keep marker lines and metadata outside collapsed sections. Put long local source or plan snapshots, and long execution-state ledgers, inside GitHub <details> blocks so issue comments are readable by default while raw comment content still remains recoverable. For execution-state comments, keep <!-- execute-from-tracking-issue:state:v1 --> and the short status fields outside the collapsed block, then keep the canonical task ledger as normal Markdown inside the block.

Workflow

1. Read and classify the issue:
   • Run gh issue view <issue> --json number,title,state,body,comments,labels,url.
   • Confirm this is a plan-tracking issue or an equivalent issue with source and plan snapshots.
   • Identify latest source snapshot, plan snapshot, execution-state comment, session log, validation comment, linked PRs, and blockers.
2. Recover the execution source:
   • Prefer issue-hosted source and plan snapshots over local files.
   • If snapshots are missing but local source/plan files exist, post source and plan snapshot comments before editing.
   • If both issue snapshots and local source/plan files are missing, stop and ask for the missing source.
3. Establish issue-backed execution state:
   • Treat the latest execute-from-tracking-issue:state:v1 comment as the durable ledger.
   • If no state comment exists, initialize one from the plan with status, target scope, task ledger, validation plan, blockers, and next task.
   • Run tracking-issue-lifecycle.sh --dry-run when marker or dashboard freshness is uncertain.
   • Update the issue body dashboard with a short current-state summary and links to snapshot/state comments; use --repair-body for a body-only dashboard repair when append-only comments are already current.
4. Execute within selected scope:
   • Use whole issue/plan when the user provides no selector.
   • If whole-scope execution is too large or risky, propose a staged execution window and wait for user confirmation.
   • Read relevant code/docs/tests before editing. Preserve unrelated dirty work.
   • For production behavior changes, capture failing-test evidence or record an explicit waiver in the issue state.
   • For browser-facing acceptance, use browser-qa evidence and link artifact paths from the issue state.
5. Persist progress to the issue:
   • Start checkpoint: post or update the latest state comment before code edits; include current task, next task, branch, and canonical task ledger columns. Leave the status summary visible, then collapse the task ledger by default with the marker line outside the collapsed block.
   • Post one execute-from-tracking-issue:session:v1 comment per meaningful execution session.
   • Post execute-from-tracking-issue:validation:v1 comments for validation commands, pass/fail status, summaries, and artifact paths.
   • PR-open checkpoint: update state/session comments with the branch, commit, and PR number or URL.
   • PR-merge checkpoint: post validation or session evidence that names the merged PR before closeout.
   • Complete checkpoint: latest state has Status: complete, all task rows are done or explicitly deferred, and evidence is linked.
   • Before PR merge, issue auto-close, closeout, or final success reporting, run the lifecycle helper with --require-complete. A plain closeout-style comment is not a substitute for a complete execute-from-tracking-issue:state:v1 ledger.
   • Blocked checkpoint: latest state has Status: blocked, blocker detail, failed validation or missing input, and an exact unblock action.
   • Update the issue dashboard after each checkpoint with current status, next task, blockers, linked PR/commit, and latest validation.
   • Re-run tracking-issue-lifecycle.sh --dry-run before handoff or closeout to catch stale dashboard links.
6. Finish or stop:
   • If complete, validate, create a semantic commit, push a branch, and open a PR by default for the completed implementation scope via pr:create-feature-pr (for feat/* branches) or pr:create-bug-pr (for fix/* branches) — never invoke gh pr create directly — unless the user requests local-only work, direct push, or project policy says otherwise.
   • If complete, post a final summary comment with changed files, validation, PR/commit links, and residual risks.
   • Do not merge the PR unless the user explicitly requests delivery or project policy says issue-backed execution includes merge.
   • Close the issue only when the user asked for closure or project policy says issue-backed execution closes on completion.
   • If blocked, leave the issue open with the exact unblock action.

Relationship To Nearby Skills

• plan-tracking-issue: creates or prepares the tracking issue and should snapshot the source and plan to issue comments before this skill becomes the executor.
• execute-from-plan: use when local docs/plans/<slug>/ files and sibling execution-state docs remain the execution source of truth.
• deliver-github-pr: use when the user explicitly wants the opened PR carried through checks, fixes, merge, and post-merge cleanup.
• deliver-dispatch-plan: use for heavyweight GitHub orchestration with sprint approvals, subagent lanes, plan branches, PR gates, and close gates.
• issue-follow-up: use for generic issue timelines that do not need plan snapshot recovery or issue-backed execution state.
• Shared issue lifecycle tool (skills/workflows/issue/_shared/lib/manage_issue_lifecycle.sh): lower-level issue body/comment/open/close operations when deterministic issue mutation is needed.

Comment Templates

Source snapshot comment:

<!-- plan-tracking-issue:snapshot:v1 kind=source -->
## Source Snapshot

- Source path: `<path-or-url>`
- Captured at: YYYY-MM-DD HH:mm TZ
- Source type: discussion-to-implementation-doc | review-to-improvement-doc | existing issue/spec | plan-only waiver

<details>
<summary>Source content</summary>

## Snapshot Content

<Paste the local source Markdown directly below. Do not wrap local Markdown snapshots in code fences; renderable issue preview is intentional.>

</details>

Plan snapshot comment:

<!-- plan-tracking-issue:snapshot:v1 kind=plan -->
## Plan Snapshot

- Plan path: `<path>`
- Captured at: YYYY-MM-DD HH:mm TZ

<details>
<summary>Plan content</summary>

## Snapshot Content

<Paste the local plan Markdown directly below. Do not wrap local Markdown snapshots in code fences; renderable issue preview is intentional.>

</details>

Execution-state comment:

<!-- execute-from-tracking-issue:state:v1 -->
## Execution State

- Status: not-started | in-progress | blocked | validating | complete
- Target scope: whole issue | <task/phase/sprint/priority selector>
- Execution window: whole issue | <confirmed staged window>
- Current task: <task id or summary>
- Next task: <task id or summary>
- Last updated: YYYY-MM-DD HH:mm TZ
- Branch/commit/PR: <optional>

<details>
<summary>Full task ledger</summary>

| ID | Status | Task | Evidence | Notes |
| --- | --- | --- | --- | --- |

</details>