---
name: plan-tracking-issue
description:
  Open or preview a provider-aware GitHub or GitLab tracking issue for a docs/plans plan bundle, bootstrapping the source doc and plan first
  when the user has a converged feature discussion but no plan file yet.
---

# Plan Tracking Issue

Create a lightweight provider issue for a plan bundle; when no plan exists, bootstrap the source doc and plan first.

## Contract

Prereqs:

- Run inside the target git repository or pass a provider/repository override.
- Either a plan file already exists, usually `docs/plans/<slug>/<slug>-plan.md`, or the conversation has converged enough to create a
  `discussion-to-implementation-doc` source artifact and `create-plan` plan bundle.
- Existing plans have exactly one primary source artifact or a recorded plan-only waiver.
- Bootstrap-from-discussion mode has enough user-provided or locally verifiable context to separate facts, decisions, assumptions, scope,
  acceptance criteria, and open questions.
- Live provider issue creation requires committed local plan and source files. Staged, unstaged, or untracked plan/source files are not
  enough for live issue creation; use `--dry-run` while drafting, then commit the plan bundle before opening the issue.
- `python3` is available on `PATH`.
- Live GitHub mode requires `gh` on `PATH` and `gh auth status` succeeds.
- Live GitLab mode requires `glab` on `PATH` and `glab auth status` succeeds.

Inputs:

- Existing plan path (`--plan <path>`) when available.
- For bootstrap-from-discussion mode: user request, converged discussion context, slug/title constraints if provided, and any relevant repo
  context needed by `discussion-to-implementation-doc` and `create-plan`.
- Optional primary source override (`--source <path-or-url>`). If omitted, the script reads the plan's `Read First` `Primary source` line.
- Optional execution-state path (`--execution-state <path>`). If omitted, infer `docs/plans/<slug>/<slug>-execution-state.md` from the
  plan filename when possible.
- Provider (`--provider github|gitlab|auto`, default `auto`).
- Optional repository override (`--repo <owner/repo|group/project>`).
- Optional metadata: `--title`, repeated `--label`, repeated `--assignee`, and `--milestone`.
- GitHub-only optional metadata: repeated `--project`.
- GitLab-only optional metadata: `--due-date`, `--weight`, and `--confidential`.
- Safety/output controls: `--dry-run`, `--body-out <path>`, and `--issue-url-out <path>`.

Outputs:

- In bootstrap-from-discussion mode: a source artifact, usually `docs/plans/<slug>/<slug>-discussion-source.md`, followed by a plan file at
  `docs/plans/<slug>/<slug>-plan.md`.
- A provider issue URL in live mode, or `DRY-RUN-TRACKING-ISSUE-URL` in dry-run mode.
- A normalized issue body that links the plan, primary source, inferred execution state, provider, and next action.
- For GitHub tracking issues intended for issue-backed execution, append-only source and plan snapshot comments with stable markers:
  - `<!-- plan-tracking-issue:snapshot:v1 kind=source -->`
  - `<!-- plan-tracking-issue:snapshot:v1 kind=plan -->`
  Long local snapshot content is collapsed by default with GitHub `<details>` blocks while marker lines and metadata stay outside the
  collapsed section for parser recovery.
- Optional body artifact written to `--body-out`.
- Optional URL artifact written to `--issue-url-out`.
- Existing-plan mode does not create another plan or mutate the plan file by default.
- No execution-state file is created merely for issue tracking. The issue records the inferred or explicit execution-state path as `exists`
  or `expected`; `execute-from-plan` creates or updates the ledger when execution starts.
- Live mode verifies that the local plan file and local primary source file are committed in `HEAD` and have no staged or unstaged changes
  before calling `gh issue create` or `glab issue create`. URL sources and explicit plan-only waivers are recorded without a local file
  commit check.

Exit codes:

- `0`: success
- `1`: runtime failure / provider command failure
- `2`: usage error

Failure modes:

- Missing or unreadable plan path in existing-plan mode.
- Missing plan plus insufficient discussion/source context to create a useful source doc and plan.
- Source doc or plan creation is blocked by project preflight, missing repo context, or validation failure.
- Missing primary source and no plan-only waiver is present.
- Provider cannot be inferred from git remote and `--provider auto` was used.
- Provider-specific unsupported flags are supplied (`--project` with GitLab, `--due-date`/`--weight`/`--confidential` with GitHub).
- Live mode is requested while the plan file or local primary source file is untracked, staged but uncommitted, or modified after commit.
- Required provider CLI or auth is unavailable in live mode.
- `gh issue create` or `glab issue create` fails.

## Modes

- Existing-plan mode: use when a plan path exists or the user points at an existing `docs/plans/<slug>/<slug>-plan.md`. Do not create a new
  source doc or plan; read the existing plan and create or preview the issue.
- Bootstrap-from-discussion mode: use when the user asks to preserve a converged feature/product/design discussion as a later plan and also
  wants a provider tracking issue. In this mode, run `discussion-to-implementation-doc` first, then `create-plan`, then create or preview
  the issue through this skill's script.

## Scripts (only entrypoints)

- `$AGENT_HOME/skills/workflows/plan/plan-tracking-issue/scripts/plan-tracking-issue.sh`

The script is the deterministic provider-issue renderer/creator. It still requires `--plan <path>`. In bootstrap-from-discussion mode, the
workflow creates the source doc and plan first, then calls the script with the saved plan path.

Snapshot comments are workflow actions after the issue URL exists; they are not embedded in the issue body renderer.

## Workflow

1. Classify the request:
   - If the user provides or clearly references an existing plan file, use existing-plan mode.
   - If no plan exists and the user asks to preserve a converged feature discussion as a plan plus provider issue, use
     bootstrap-from-discussion mode.
   - If the discussion is not converged enough for execution planning, ask the minimum blocking questions before writing docs.
   - If the user only wants to preserve conclusions without task sequencing or issue tracking, use `discussion-to-implementation-doc`
     directly instead of this skill.
2. In existing-plan mode:
   - Confirm the plan path exists.
   - Confirm the plan has exactly one primary source artifact or a recorded plan-only waiver.
   - Do not create another source doc or plan.
3. In bootstrap-from-discussion mode:
   - Follow project preflight for docs edits.
   - Use `discussion-to-implementation-doc` to save the implementation-readiness source artifact, usually as
     `docs/plans/<slug>/<slug>-discussion-source.md`.
   - Use `create-plan` to save `docs/plans/<slug>/<slug>-plan.md` with the source artifact under `Read First`.
   - Validate the plan through the `create-plan` workflow before creating or previewing the provider issue.
   - Do not create or update `<slug>-execution-state.md` unless the user also asks to start execution or project policy explicitly requires
     a pre-created execution ledger.
4. Resolve the provider:
   - Use an explicit `--provider` when the target platform is known.
   - Use `--provider auto` only when the repository remote clearly identifies GitHub or GitLab.
5. Resolve the primary source for the saved plan:
   - Prefer the explicit `--source`.
   - Otherwise parse the plan's `Read First` `Primary source` line.
   - Preserve plan-only waivers as a source value; do not invent a source document.
6. Render a concise issue body:
   - State that the plan remains the source of truth.
   - Link the primary source, plan, and execution state path.
   - Record the provider/repository and next action.
7. Run the script with `--dry-run` before live creation when provider/repo/metadata is uncertain.
8. Before live creation, verify persistence for local files:
   - Confirm the plan file is committed in `HEAD`.
   - If the primary source is a local file, confirm it is committed in `HEAD`.
   - Confirm both files have no staged or unstaged changes.
   - If this check fails, commit the plan bundle first or stay in `--dry-run` mode; do not open a live tracking issue that only references
     uncommitted local files.
9. In live mode, create exactly one issue through the selected provider CLI:
   - GitHub: `gh issue create`.
   - GitLab: `glab issue create`.
10. For GitHub issues that may later be executed through `execute-from-tracking-issue`:
    - Post a source snapshot comment with `<!-- plan-tracking-issue:snapshot:v1 kind=source -->`.
    - Post a plan snapshot comment with `<!-- plan-tracking-issue:snapshot:v1 kind=plan -->`.
    - Include content for local source and plan files as renderable GitHub Markdown. Do not wrap the comment body or local Markdown snapshot
      content in outer `markdown` / `md` code fences; issue preview readability is intentional.
    - Place long local source or plan Markdown inside a collapsed `<details>` block with a short `<summary>` label, leaving marker lines and
      snapshot metadata outside the collapsed section.
    - For URL or waiver sources, record the source value and why no local content was snapshotted.
    - Do not include secrets, credentials, private keys, or raw logs in snapshot comments.
11. Report the issue URL, snapshot comment status, and any body artifact path.

## Relationship To Nearby Skills

- `discussion-to-implementation-doc`: in bootstrap-from-discussion mode, use it first to preserve converged feature/product/design
  conclusions as the plan's primary source artifact.
- `create-plan`: in bootstrap-from-discussion mode, use it after the source doc and before provider issue creation. Existing-plan mode skips
  it to avoid duplicate plans.
- `create-dispatch-plan`: use instead of `create-plan` inside bootstrap mode only when the user explicitly needs dispatch-ready sizing,
  scorecards, PR grouping, or subagent-reviewed execution modeling.
- `issue-follow-up`: use for GitHub-only problem timelines that are not tied to a plan bundle.
- `issue-lifecycle`: use when the GitHub Issue itself is the planning source of truth with task decomposition.
- `execute-from-tracking-issue`: use when the GitHub issue-hosted source/plan snapshots should become the execution source of truth,
  especially after local `docs/plans/` cleanup.
- `dispatch-plan-delivery`: use only for heavyweight GitHub execution orchestration where `1 plan = 1 issue` and close gates require merged
  sprint/integration PRs.

## Notes

- This skill is opt-in. `create-plan` still does not open live provider issues by default; issue creation happens only when this skill is
  explicitly selected or requested.
- The issue is a tracker, not a replacement source artifact. Keep detailed requirements, findings, and execution sequencing in the source
  doc and plan bundle.
- Once `execute-from-tracking-issue` starts from a GitHub tracking issue, the issue-hosted snapshots and execution comments become the
  durable execution record; local plan files can then be cleaned up after the usual reference checks.
- If a repository needs GitLab Issue lifecycle operations beyond creation and comments, add a GitLab-specific lifecycle skill instead of
  stretching the GitHub `issue-lifecycle` contract.
