# Issue Workflows

Issue skills split into two different operating models. Choose the model from the execution shape before starting work; do not mix their
state contracts in the same issue unless a plan explicitly says to migrate.

## Plan Tracking Issue Flow

Use this flow when a normal implementation plan needs a GitHub issue as a durable timeline, but the work can still be performed by the main
agent or ordinary PR workflows.

Best fit:

- A `docs/plans/<slug>/` plan bundle exists or is created from a converged discussion.
- The issue should preserve source, plan, state, validation, and sprint/session progress.
- PR creation, delivery, or merge policy is explicit and may vary by run.
- The user wants final review before closing the issue.

Skill sequence:

1. `plan-tracking-issue`
   Creates or previews the provider issue and posts source/plan snapshot comments:
   `plan-tracking-issue:snapshot:v1 kind=source` and `plan-tracking-issue:snapshot:v1 kind=plan`.
2. `execute-from-tracking-issue`
   Executes from issue-hosted snapshots, appends state/session/validation comments, updates the issue dashboard, and opens PRs by default.
   It does not merge or close unless the user or project policy explicitly says so. Use
   `execute-from-tracking-issue/scripts/tracking-issue-lifecycle.sh` for dry-run lifecycle audits, dashboard rendering, stale-link detection,
   completion gating, and body-only dashboard repair during execution. Before merge, auto-close, closeout, or final success reporting, run
   the lifecycle helper with `--require-complete`.
3. `deliver-tracking-issue` (optional one-shot delivery)
   Resumes the issue-backed plan, executes remaining tasks, opens PRs, uses the shared delivery specialist review gate for every PR, repairs
   concrete findings, posts provider-side delivery review outcome comments, merges PRs through provider PR delivery gates, updates
   issue-hosted state/session/validation evidence, then closes through `tracking-issue-closeout`.
   Use this when the user asks to deliver and close the tracking issue instead of stopping at PR open or manual final review.
4. `tracking-issue-closeout`
   Runs after execution is complete and review/closure is approved. It checks the snapshots, execution state, latest completed session,
   validation evidence, linked PRs, and approval; then it repairs the final dashboard body, posts a closeout comment, closes the issue, and
   reports the outcome.
   If a tracking issue was already closed before the final dashboard was repaired, rerun `tracking-issue-closeout` with `--repair-closed`.
   Add `--finalize-closed` only when an already closed, otherwise complete issue is missing the canonical closeout marker.

Durable record:

- Issue body is the mutable current/final dashboard.
- Source/plan snapshots, execution state, session logs, validation evidence, and closeout are append-only comments.
- Local `docs/plans/` files may remain for review or cleanup, but the issue comments are enough to recover execution context after this flow
  starts.
- The canonical issue-backed task ledger is `ID | Status | Task | Evidence | Notes`; local execution-state Markdown is only a scratchpad or
  recovery input after issue-backed execution starts.
- Long issue-hosted execution-state comments leave the short state fields visible by default and collapse the canonical task ledger, with the
  marker line outside the collapsed block.
- Closeout depends on the latest issue-hosted execution state, not a plain summary comment. The state must be `complete`, and every task row
  must be `done` or `deferred`.

Do not use this flow for multi-subagent task-lane orchestration. If the issue itself owns task rows, sprint gates, subagent assignments, and
close gates, use the dispatch flow instead.

## Dispatch Multi-Subagent Flow

Use this flow when a plan issue is the live orchestration surface for subagent-owned task lanes, sprint gates, PR linkage, and close gates.

Best fit:

- Implementation is split into task lanes assigned to subagents.
- The main agent should orchestrate, review, and close gates, not implement task lanes directly.
- The issue body has a task decomposition table or `plan-issue` runtime state.
- Sprint acceptance, PR linkage, review decisions, and final close must be deterministic.

Skill sequence:

1. `dispatch-plan-delivery`
   Starts or resumes the plan issue runtime, dispatches sprint/task lanes, records sprint comments, links PRs, runs acceptance gates, and
   closes through `plan-issue close-plan` when all final gates pass.
2. `dispatch-subagent-pr`
   Subagent-owned implementation lane workflow. It creates or updates the assigned branch/PR and reports task-level validation.
3. `dispatch-pr-review`
   Main-agent PR review and issue-sync workflow. It mirrors review decisions and follow-up links back to the issue timeline.
4. `dispatch-issue-closeout`
   Closes an existing dispatch issue runtime when subagent lanes, PRs, review approval, and merged-PR gates are satisfied.

Durable record:

- Issue task rows and `plan-issue` runtime state are the execution source of truth.
- Subagent implementation details stay on PRs; issue comments summarize status and link to PR/review evidence.
- Final close is gated by `plan-issue close-plan`, not by ad hoc `gh issue close`.

Do not use this flow for lightweight plan tracking where the issue only mirrors source/plan snapshots and session comments. That is the plan
tracking issue flow.

## Quick Choice

| Situation | Use |
| --- | --- |
| One plan, issue-hosted snapshots, ordinary PRs, user closes after review | `plan-tracking-issue` -> `execute-from-tracking-issue` -> `tracking-issue-closeout` |
| Plan-tracking issue dashboard drift during execution | `tracking-issue-lifecycle.sh --dry-run` then `--repair-body` when append-only comments are current |
| Plan-tracking issue completion gate before merge or close | `tracking-issue-lifecycle.sh --dry-run --require-complete` |
| Already closed plan-tracking issue with stale final dashboard | `tracking-issue-closeout --repair-closed` |
| Already closed plan-tracking issue missing closeout marker | `tracking-issue-closeout --repair-closed --finalize-closed` |
| Main-agent owns implementation and just needs a durable issue timeline | `issue-follow-up` plus normal implementation/PR workflow |
| Existing plan-tracking issue should be delivered through PR review/repair/merge and closed | `deliver-tracking-issue` |
| Issue owns task rows, subagent lanes, sprint acceptance, and final gates | `dispatch-plan-delivery` / `dispatch-issue-closeout` |
| Generic issue edit/comment/close without plan markers | `issue-lifecycle` |
