Astro Issue

---
name: astro-issue
description: Drives one ASTROLABE GitHub issue through the mandatory lifecycle — pick, claim, verify prior progress, scoped work, FSV proof, evidence, close. Use when starting, resuming, or closing work on a GitHub issue, choosing the next issue, checking a DoD box, or swapping status labels. Not for filing new issues (use astro-new-issue) or pausing mid-issue (use astro-handoff).
argument-hint: [issue-number | pick]
allowed-tools: Bash(gh issue *), Bash(gh api *), Bash(git status *), Bash(git log *), Bash(git diff *)
---

# Issue lifecycle driver

Issue to work: `$ARGUMENTS` (if `pick` or empty, apply step 1 to choose one).

GitHub issues are the single source of truth. If it isn't recorded on an issue, it didn't happen. Every state-changing comment below carries an `astro-telemetry/v1` block — see `${CLAUDE_PROJECT_DIR}/.claude/skills/astro-telemetry/references/spec.md`. Comment templates: [references/templates.md](references/templates.md).

## 1. Pick

- `gh issue list --label status:ready --json number,title,milestone,labels --limit 100`
- Choose from the **lowest-numbered open milestone** (spine order `P0 → P1 → P2 → (P3 ∥ P4) → P5 → P6 → (P7 ∥ P8) → P9`, EPIC #65).
- Never start `status:blocked` or `status:needs-spec`. If an issue has `status:in-progress` with a claim comment newer than 48h **from another live session**, pick a different one; this is otherwise a sole-agent repo — a stale prior claim never prevents continuation.
- Anything touching `crates/astrolabe-server` (especially `src/migration.rs`, under decomposition per #85) is sequential-only work; do not run it concurrently with another server-touching effort.

## 2. Claim

- Comment: what you are about to do + plan in ≤5 bullets + telemetry block (kind `claim`).
- Swap label: `gh issue edit N --remove-label status:ready --add-label status:in-progress`.

## 3. Verify the claim before working

- Read the issue body **and every comment** (`gh issue view N --comments`). Prior sessions record completed work there.
- Never redo a checked DoD item. Re-verify it instead (re-run its named manual FSV against the real artifact) and note the result.

## 4. Work in scope

- Implement ONLY the issue's Scope section. Discovered adjacent work → file via astro-new-issue and link it; never expand scope in place.
- Every verification follows astro-fsv (source-of-truth readback, never API echoes; real data only, no mocks). FSV-only doctrine (owner directive 2026-07-13): no aggregate/gate suite exists or is required.
- Every commit body references the issue (`Refs #N`; `Closes #N` only on the final commit **after** FSV evidence exists — never on server-pending work, see astro-fanout).
- Never write progress prose into `docs/astrolabe-blueprint.md` (design corrections only).
- No `todo!()`/stubs on shipped paths; fail-closed `{code, message, remediation}` errors; no silent fallback — every degradation labeled, every skip counted.

## 5. Prove, then check the box

A DoD checkbox may be checked only in the same session that ran its verification, with the manual FSV command + persisted readback pasted in a comment (kind `evidence`). Tests are never evidence (owner directive 2026-07-14).

## 6. Verify (FSV)

Build the real artifact natively and FSV the changed behavior per astro-fsv: real execution, independent persisted-state readback, edge-case triad. `DEFERRED[...]` / `SKIP[...]` labels are **not** passing evidence. A verification that fails for a pre-existing reason: attribute it (`git log -S`), file/link an issue — never skip silently.

## 7. Close

1. Closing comment: command, native execution context, output tail, telemetry block (kind `close`).
2. Every DoD box checked with evidence → `gh issue close N`.
3. Tick the issue's checkbox in EPIC #65; remove the `status:*` label.
4. Commit and push the verified state immediately.
5. Verify `target/` is absent.

## Stopping early

Use astro-handoff. Never leave an issue silently in-progress.