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

```bash
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.
- `dispatch-plan-delivery`: use for heavyweight GitHub orchestration with sprint approvals, subagent lanes, plan branches, PR gates, and close
  gates.
- `issue-follow-up`: use for general issue follow-up that does not need plan snapshot recovery or issue-backed execution state.
- `issue-lifecycle`: use for lower-level issue body/comment/open/close operations when deterministic issue mutation is needed.

## Comment Templates

Source snapshot comment:

```markdown
<!-- 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:

```markdown
<!-- 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:

```markdown
<!-- 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>
```
