--- name: issue-lifecycle description: > Drive the @swamp/issue-lifecycle model for interactive issue triage and plan iteration against swamp-club lab issues. Use when the user wants to triage a swamp-club issue, generate an implementation plan, or iterate on a plan with feedback. Also handles retroactive lifecycle creation for ad-hoc work via "prepare to ship". Triggers on "triage issue", "triage #", "issue plan", "review plan", "iterate plan", "approve plan", "issue lifecycle", "prepare to ship", "ready to ship". --- # Issue Lifecycle Skill Interactive triage and implementation planning for swamp-club lab issues using the `@swamp/issue-lifecycle` extension model. This skill drives the model conversationally — the human steers, you execute. The model operates on swamp-club lab issue numbers. Every step records a structured lifecycle entry against the issue in swamp-club and transitions its status as the work progresses. There is no GitHub integration — the issue must already exist in swamp-club before you start. ## Core Principles **Always use the installed `swamp` binary.** Every `swamp` command in this skill must invoke the installed binary from `$PATH` — never `deno run dev` or any other Deno-based invocation. Before running any swamp command, verify the binary exists: ``` which swamp ``` If `which swamp` fails (binary not found), **stop immediately** and tell the human: "The `swamp` binary is not installed or not on your PATH. Install it before continuing." Do not fall back to `deno run dev`. **Never auto-approve.** Always stop and show the plan to the human. Always ask for feedback. Only call `approve` when the human explicitly says to proceed. ## Prepare to Ship (Ad-Hoc Work) When the user says **"prepare to ship"** (or "ready to ship", "prepare to ship this work"), they have completed ad-hoc work that is not linked to an existing issue. The lifecycle still needs a tracking issue for verification and attestation to flow through. **This flow is fully automatic — do not ask for confirmation at each step.** ### Steps 1. **Summarize the work.** Inspect the current branch: `git log main..HEAD`, `git diff --stat main..HEAD`. Build a title and summary from the commits and changed files. 2. **Create a tracking issue in swamp-club.** There is no `swamp issue create` — pick the type-specific subcommand (`feature`, `bug`, or `security`). The CLI cannot file `platform` issues, so classify ad-hoc work as `feature` or `bug`: ``` swamp issue feature --title "" --body "<summary of work done>" --json ``` Read `number` from the JSON output — that is `<N>` in every command below. `--body` requires `--title`; without both, the command opens an editor. 3. **Start the lifecycle:** ``` swamp model @swamp/issue-lifecycle method run start issue-<N> --input issueNumber=<N> ``` 4. **Fast-forward to implementing:** ``` swamp model @swamp/issue-lifecycle method run fast_forward issue-<N> \ --input summary="<summary>" \ --input steps='<JSON array of plan steps>' \ --input testingStrategy="<testing approach>" ``` Build the plan steps retroactively from the actual work — each step should describe a logical unit of change with its files. The testing strategy should reflect how the changes were validated. 5. **Transition to `verifying`.** `fast_forward` leaves the lifecycle at `implementing`, and `post_attestation` is only accepted from `verifying` — so this transition is required, not optional: ``` swamp model @swamp/issue-lifecycle method run verify issue-<N> \ --input commit=$(git rev-parse HEAD) \ --input branch=$(git branch --show-current) ``` 6. **Proceed with normal verification.** Read [references/verification.md](references/verification.md) and continue from its step 2 (Run Verification) through verification_passed → post_attestation → link_pr. Step 1 there is the `verify` call just made — do not repeat it. 7. **Drive the lifecycle to `done`.** `link_pr` only reaches `pr_open` — it is not the end of the flow, and stopping there leaves the issue parked. Walk the rest: `pr_merged` (→ `releasing`), `ship` or `complete` (→ `notify`), `notify` or `skip_notify` (→ `summarizing`), then `summarize` (→ `done`). See "Closing Out a Shipped Issue" below for the exact commands. ### Example ``` User: prepare to ship this work Agent: 1. git log main..HEAD → "Add retry logic to HTTP client" 2. swamp issue feature --title "Add retry logic to HTTP client" --body "..." --json → {"number": 247, ...} 3. swamp model @swamp/issue-lifecycle method run start issue-247 --input issueNumber=247 4. swamp model @swamp/issue-lifecycle method run fast_forward issue-247 \ --input summary="Add exponential backoff retry to HTTP client" \ --input steps='[{"order":1,"description":"Add retry wrapper","files":["src/http/client.ts"]}]' \ --input testingStrategy="Unit tests for retry logic added in client_test.ts" 5. swamp model @swamp/issue-lifecycle method run verify issue-247 \ --input commit=$(git rev-parse HEAD) --input branch=$(git branch --show-current) 6. Proceed to verification (references/verification.md, from step 2)... ``` ## Repository Configuration This skill reads repo-specific conventions from `agent-constraints/` at the repository root. If these files exist, they customize how each phase works: - `agent-constraints/adversarial-dimensions.md` — review criteria and dimensions - `agent-constraints/planning-conventions.md` — analysis and documentation requirements - `agent-constraints/triage-conventions.md` — codebase exploration and bug reproduction - `agent-constraints/code-conformance-dimensions.md` — code vs plan review criteria - `agent-constraints/implementation-conventions.md` — build, verify, and PR conventions - `agent-constraints/verification-conventions.md` — container sandbox and verification workflow configuration If these files do not exist, the skill uses generic defaults documented in each reference file. ## Lifecycle Phases Each phase has detailed instructions in a reference file. Read only the reference you need for the current phase. ### Phase 1: Triage (steps 1–4) Read [references/triage.md](references/triage.md) when starting a new triage or resuming an issue in the `triaging` phase. Covers: starting the lifecycle (using direct type execution to auto-create the model and fetch issue context in one command), reading the codebase, classifying the issue, and reproducing bugs. The first command to run is always the existence check: ``` swamp data get issue-<N> state-main --json ``` - If this **returns data**, the model already exists — check the `phase` field and go to the "Resuming a Session" table below. **Do NOT call `start`.** - If this **fails** (model not found), the issue is new — run: ``` swamp model @swamp/issue-lifecycle method run start issue-<N> --input issueNumber=<N> ``` This fetches the issue from swamp-club and writes context automatically — do NOT use `gh issue view` or any other mechanism to fetch issue data. ### Phase 2: Planning (steps 5–7) Read [references/planning.md](references/planning.md) after triage is complete. Covers: generating the implementation plan, applying repo-specific planning conventions, and presenting to the human. ### Phase 3: Adversarial Review & Iteration Read [references/adversarial-review.md](references/adversarial-review.md) **immediately after every `plan` or `iterate` call — no exceptions.** Planning and adversarial review are always paired: you never present a plan without running the review first. Covers: challenging the plan across repo-specific dimensions, verifying against the codebase, recording findings, presenting to the human, and the iteration loop until approval. ### Phase 4: Implementation & Code Conformance Review Read [references/implementation.md](references/implementation.md) after plan approval. Covers: signalling implementation start and doing the work. After the code is written, read [references/code-conformance-review.md](references/code-conformance-review.md) **before verification.** This adversarially compares the implemented code against the approved plan. Deviations are expected — they just need a documented justification. ### Phase 4a: Verification Loop Read [references/verification.md](references/verification.md) **after code conformance review is complete.** This runs the same checks as CI (lint, test, compile, agent reviews) inside a container sandbox before the PR opens. The agent iterates — fixing failures and re-verifying — until all steps pass. Only then can a PR be created. ### Phase 5: Contributor Notification After `ship` or `complete`, the lifecycle enters the `notify` phase. This is where you decide whether to thank the issue author: - If the issue author is an **external contributor** (not a repo collaborator), call `notify` to post a thank-you ripple mentioning them by handle. - If the issue author is a **collaborator**, call `skip_notify` to proceed. Check collaborator status with: ``` gh api /repos/swamp-club/swamp/collaborators --jq '.[].login' | grep -qx '<author>' ``` If the author is NOT in the collaborator list, they are external — call `notify`. Otherwise call `skip_notify`. ### Phase 6: Session Summary After `notify` or `skip_notify`, the lifecycle enters the `summarizing` phase. Read [references/implementation.md](references/implementation.md) — section 7 covers the summary step. Restate the original problem and the delivered outcome in plain language, then close out the lifecycle. This final check ensures the work actually addressed the issue. All three inputs are required — `summarize` fails validation without them: ``` swamp model @swamp/issue-lifecycle method run summarize issue-<N> \ --input originalProblem="<problem>" \ --input deliveredOutcome="<outcome>" \ --input outcomeMet=true ``` ## Classification Types The `triage` method classifies issues into one of four types (matching swamp-club): - `bug` — something is broken or behaving incorrectly - `feature` — a request for new functionality or enhancement - `platform` — admin-only platform infrastructure work - `security` — security vulnerability or hardening work `platform` is accepted by the `triage` method, but the CLI can neither file nor switch an issue to it — `swamp issue bug|feature|security` and `swamp issue edit --type` accept only the other three. Classify an existing issue as `platform` if it fits; never try to create one. Two additional classification details are captured in the classification record but do NOT map to separate swamp-club types: - `isRegression` — set to `true` when the bug previously worked. Implies `type: bug`. Look for signals like "this used to work", "stopped working after", or git history showing recent changes to the affected code. - Low-confidence classifications — if you cannot classify the issue confidently, use `confidence: low` and populate `clarifyingQuestions`. Do not guess the type — ask the human before calling `triage`. ## Reviewing Plan History To review a specific plan version: ``` swamp model @swamp/issue-lifecycle method run review issue-<N> --input version=<V> ``` To see all model data: ``` swamp model output search issue-<N> --json ``` ## Resuming a Session If the human comes back to an in-progress issue, check the current phase: ``` swamp data get issue-<N> state-main --json ``` Read the `phase` field from the response. **Do NOT call `start` to resume** — `start` unconditionally resets the phase to `triaging`, destroying progress. Use this table to determine what to do next: | Phase | Action | | ---------------- | -------------------------------------------------------------------------- | | `triaging` | Read [references/triage.md](references/triage.md) | | `classified` | Read [references/planning.md](references/planning.md) | | `plan_generated` | Read [references/adversarial-review.md](references/adversarial-review.md) | | `approved` | Read [references/implementation.md](references/implementation.md) | | `implementing` | Run code conformance review, then verify | | `verifying` | Read [references/verification.md](references/verification.md) | | `pr_open` | Wait 3 min, then check PR: `pr_merged` if merged, `pr_failed` if failed | | `pr_failed` | Fix the issue, then `link_pr` (new PR) or `implement` (major rework) | | `releasing` | Check release build: `ship` when done, or `complete` as fallback | | `notify` | Check if author is external: `notify` to thank them, `skip_notify` to skip | | `summarizing` | Call `summarize` — needs originalProblem, deliveredOutcome, outcomeMet | | `done` | Nothing to do — lifecycle is complete | The canonical phase list lives in the `TRANSITIONS` constant in `extensions/models/_lib/schemas.ts`. ## Closing Out a Shipped Issue When a PR has already merged and the lifecycle just needs to be marked done: 1. Check the current phase: ``` swamp data get issue-<N> state-main --json ``` 2. If the phase is `implementing`, link the PR first: ``` swamp model @swamp/issue-lifecycle method run link_pr issue-<N> --input url=<PR URL> ``` 3. If the phase is `pr_open`, record the merge: ``` swamp model @swamp/issue-lifecycle method run pr_merged issue-<N> ``` 4. If the phase is `releasing`, ship it: ``` swamp model @swamp/issue-lifecycle method run ship issue-<N> ``` 5. If the phase is `notify`, check if the author is external and either thank them or skip: ``` swamp model @swamp/issue-lifecycle method run notify issue-<N> swamp model @swamp/issue-lifecycle method run skip_notify issue-<N> ``` 6. If the phase is `summarizing`, record the summary: ``` swamp model @swamp/issue-lifecycle method run summarize issue-<N> \ --input originalProblem="<problem>" --input deliveredOutcome="<outcome>" --input outcomeMet=true ``` 7. For quick close-out, `complete` still works from `implementing`, `pr_open`, or `releasing` (transitions to `notify`, then `notify`/`skip_notify`, then `summarize`). ## Key Rules 1. **Never use `gh` to fetch issue data.** All issue context comes from swamp-club via the `start` method — not from GitHub. The only place `gh` is used in this skill is checking collaborator status during contributor notification. 2. **Never skip the feedback loop.** Always show the plan. Always ask. 3. **Never call approve without explicit human approval.** 4. **Persist everything through the model.** Don't just have a conversation — call the model methods so state survives context compression and sessions. 5. **swamp-club is the source of truth.** Every state transition posts a lifecycle entry and transitions the issue status in swamp-club automatically. You don't need to manually update the issue. 6. **Read the codebase thoroughly** before generating the plan. The plan should reference specific files, functions, and test paths. 7. **Follow the planning conventions for this repository.** Read `agent-constraints/planning-conventions.md` if it exists. 8. **Never open a PR without asking first.** Present the changes summary and wait for the human to confirm before creating the pull request. 9. **File unrelated issues immediately.** If you discover a bug, code smell, or problem during investigation that is NOT related to the current issue, file it as a new swamp-club issue. Do not try to fix it in the current work span — keep the scope focused. 10. **Never use `deno run dev` for swamp commands.** All `swamp` invocations must use the installed binary. Run `which swamp` first — if it's missing, stop and tell the human.