Issue Lifecycle

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:

Copy code
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.

A failed method means the upstream record was not written. Lifecycle entries are the audit trail, so a method fails rather than reporting success over a dropped entry. The error names the step, the HTTP status, and swamp-club's own reason.

• Most methods roll back. The local phase is unchanged, so fix the cause and re-run the same method. Re-running is safe: a status transition that already landed is recognised as a no-op.
• notify does not roll back. If it fails after the ripple posted, the phase has already advanced — do not re-run it, or the contributor is thanked twice. Continue with summarize.
• post_attestation warns instead of failing. The attestation itself is the durable record, and re-running would file a duplicate for the same commit. The warning names the attestation id.

The most common cause is payload text the server refuses: until swamp-club#2284 is fixed, it rejects any string value that begins with a dollar sign, and any prose containing a double-quote immediately followed by one — a quoted shell variable in a code snippet, for example. Rephrase the text (name the variable in words) and re-run.

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:

   Copy code
   swamp issue feature --title "<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:

   Copy code
   swamp model @swamp/issue-lifecycle method run start issue-<N> --input issueNumber=<N>
   

4. Fast-forward to implementing:

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

   Copy code
   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 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

Copy code
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)...

Several Issues, One Piece of Work

When the work for one issue also fixes another, or an issue duplicates one that is already fixed, never close the extra issue. Read references/linked-issues.md and use link_issue on the primary issue's lifecycle, or mark_duplicate on the duplicate's own lifecycle when the other issue has already shipped. Linked issues move through status with the primary issue and ship with it.

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

Copy code
swamp data query 'modelName == "issue-<N>" && name == "state-main"' --select content --json

• If results has an entry, the model already exists — check results[0].phase and go to the "Resuming a Session" table below. Do NOT call start.
• If results is empty (model or data not found), the issue is new — run:

Copy code
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 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 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 after plan approval. Covers: signalling implementation start and doing the work.

After the code is written, read 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 after code conformance review is complete. This runs the same checks as CI (lint, test, compile, agent reviews) as host workflows 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, run notify. It checks the author against the swamp-club team roster itself: team members are skipped, anyone else is thanked with a ripple. Never check membership with GitHub — swamp-club handles are not GitHub logins.

Copy code
swamp model @swamp/issue-lifecycle method run notify issue-<N>

If the lookup fails, notify posts nothing and stays in notify. Ask the human, then re-run it, add --input force=true to thank the author anyway, or run skip_notify.

Phase 6: Session Summary

After notify or skip_notify, the lifecycle enters the summarizing phase. Read 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:

Copy code
swamp model @swamp/issue-lifecycle method run summarize issue-<N> \
  --input originalProblem="<problem>" \
  --input deliveredOutcome="<outcome>" \
  --input outcomeMet=true

If the lifecycle carries linked issues, summarize also requires linkedOutcomes, with one entry per linked issue — see references/linked-issues.md.

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:

Copy code
swamp model @swamp/issue-lifecycle method run review issue-<N> --input version=<V>

To see all model data:

Copy code
swamp model output search issue-<N> --json

Resuming a Session

If the human comes back to an in-progress issue, check the current phase:

Copy code
swamp data query 'modelName == "issue-<N>" && name == "state-main"' --select content --json

Read results[0].phase 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:

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:

   Copy code
   swamp data query 'modelName == "issue-<N>" && name == "state-main"' --select content --json
   

   The phase is results[0].phase.
2. If the phase is implementing, link the PR first:

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

   Copy code
   swamp model @swamp/issue-lifecycle method run pr_merged issue-<N>
   

4. If the phase is releasing, ship it:

   Copy code
   swamp model @swamp/issue-lifecycle method run ship issue-<N>
   

5. If the phase is notify, run notify (see Phase 5).
6. If the phase is summarizing, record the summary:

   Copy code
   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. Issue authors are swamp-club handles, so never compare them against GitHub logins.
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. An issue the same work genuinely fixes is related: link it with link_issue rather than closing it.
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.