Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 40 additions & 16 deletions issue-lifecycle/.claude/skills/issue-lifecycle/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,19 +2,23 @@
name: issue-lifecycle
description: >
Drive the @swamp/issue-lifecycle model for interactive issue triage and
plan iteration. Use when the user wants to triage a GitHub issue,
generate an implementation plan, or iterate on a plan with feedback.
Triggers on "triage issue", "triage #", "issue plan", "review plan",
"iterate plan", "approve plan", "issue lifecycle", "fix review issues",
"check CI", "ci status".
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. Triggers on "triage issue", "triage #", "issue plan",
"review plan", "iterate plan", "approve plan", "issue lifecycle".
---

# Issue Lifecycle Skill

Interactive triage and implementation planning for GitHub issues using the
`@swamp/issue-lifecycle` extension model. This skill drives the model
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 Principle

**Never auto-approve.** Always stop and show the plan to the human. Always ask
Expand Down Expand Up @@ -45,8 +49,8 @@ reference you need for the current phase.

Read [references/triage.md](references/triage.md) when starting a new triage or
resuming an issue in the `triaging` phase. Covers: creating the model instance,
fetching issue context, reading the codebase, classifying the issue, and
reproducing bugs.
fetching issue context from swamp-club, reading the codebase, classifying the
issue, and reproducing bugs.

### Phase 2: Planning (steps 6–9)

Expand All @@ -63,11 +67,30 @@ 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 & CI
### Phase 4: Implementation

Read [references/implementation.md](references/implementation.md) after plan
approval. Covers: doing the work, verifying fixes against the reproduction,
creating the PR, CI polling loop, handling failures, and completing the issue.
approval. Covers: signalling implementation start, doing the work, verifying
fixes against the reproduction, creating the PR, and completing the issue.

## Classification Types

The `triage` method classifies issues into one of three types (matching
swamp-club):

- `bug` — something is broken or behaving incorrectly
- `feature` — a request for new functionality or enhancement
- `security` — security vulnerability or hardening work

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

Expand Down Expand Up @@ -100,13 +123,14 @@ there.
2. **Never call approve without explicit human approval.**
3. **Persist everything through the model.** Don't just have a conversation —
call the model methods so state survives context compression and sessions.
4. **GitHub comments are automatic.** Every state transition posts to the issue.
You don't need to manually post comments.
4. **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.
5. **Read the codebase thoroughly** before generating the plan. The plan should
reference specific files, functions, and test paths.
6. **Follow the planning conventions for this repository.** Read
`agent-constraints/planning-conventions.md` if it exists.
7. **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 GitHub issue in the current repository. Do not try to fix it in
the current work span — keep the scope focused.
it as a new swamp-club issue. Do not try to fix it in the current work span —
keep the scope focused.
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Implementation & CI Flow
# Implementation Flow

Read this after the plan is approved and the human says to implement. The
`approve` method already transitioned the issue to "in progress" in swamp-club.
`approve` method already transitioned the swamp-club issue to `in_progress`.

## 1. Signal Implementation Started

Expand All @@ -11,16 +11,17 @@ Before writing any code, signal that implementation has begun:
swamp model method run issue-<N> implement
```

This transitions the phase to `implementing`, posts a GitHub comment, and
notifies swamp-club that work is underway. Do this **before** touching any code.
This transitions the phase to `implementing` and posts an
`implementation_started` lifecycle entry on the swamp-club issue. Do this
**before** touching any code.

## 2. Do the Implementation Work

Follow the approved plan step by step.

## 3. Verify the Fix Against the Reproduction

**Bugs and regressions only — skip for features.**
**Bugs and regressions only — skip for features and security issues.**

If a reproduction was created during triage, reuse it to confirm the fix works.

Expand All @@ -36,90 +37,21 @@ Report verification results to the human before creating the PR:

## 4. Create a PR

Read `agent-constraints/implementation-conventions.md` for PR creation guidance.
If it does not exist, create a PR using `gh pr create`.
Use the repository's normal PR tooling. Read
`agent-constraints/implementation-conventions.md` for repo-specific PR
conventions.

## 5. Record the PR Number
The issue-lifecycle model does not track PRs directly — your PR creation is
outside the model's scope. The swamp-club issue status stays at `in_progress`
until you call `complete`.

After the PR is created, link it to the issue so `ci_status` can find it:
## 5. Complete the Issue

```
swamp model method run issue-<N> record_pr \
--input prNumber=<N>
```

## 6. Wait for CI to Start

Use `sleep 180` — CI takes at least 3 minutes, so there's no point polling
earlier.

## 7. Poll for CI Results

You MUST implement an explicit polling loop — do not check once and assume done:

```
repeat:
call ci_status
parse the output — look at EVERY check's status
if ANY check is "pending", "queued", or "in_progress":
tell the human: "CI still running — N of M checks complete. Waiting 60s..."
sleep 60
go back to repeat
else:
all checks are conclusive (passed/failed) — exit the loop
```

The ci_status command:

```
swamp model method run issue-<N> ci_status
```

**Do NOT exit this loop early.** A single ci_status call that shows some checks
passed does not mean CI is done — other checks may still be running. You must
confirm that **every** check has a conclusive status (passed or failed) before
proceeding. The human can always interrupt the loop (e.g. "stop", "pause") —
respect that immediately. But the agent must never exit the loop on its own.

## 8. Show CI Results

Show results to the human, grouped by reviewer and severity:

- Which checks passed/failed
- Review comments grouped by reviewer
- Comments sorted by severity (critical first)

## 9. If Everything is Green and Approved

The PR will auto-merge. Call `complete` immediately — no need to ask the human:
Once the PR has merged and the work is done, call `complete`:

```
swamp model method run issue-<N> complete
```

## 10. If There Are Failures or Review Comments

Present them and wait for the human's direction. Parse their instruction:

- "fix the CRITICAL issues from adversarial review" →
`targetReview: "claude-adversarial-review"`, `targetSeverity: "critical"`
- "address all the review comments" → no filters
- "fix the test failures" → `targetReview: "test"`

```
swamp model method run issue-<N> fix \
--input directive="<human's instruction>" \
--input targetReview="<reviewer>" \
--input targetSeverity="<severity>"
```

## 11. After Pushing Fixes

Loop back to step 6. Wait 3 minutes, poll for CI, show results. Repeat until
clean or the human says to stop.

**IMPORTANT:** Do not break out of this loop voluntarily. The human should never
have to manually check CI or come back to ask "what happened?" — the skill stays
in the conversation and drives through to completion. If the human wants to
break out (e.g. "I'll come back to this later", "pause", "stop"), respect that
immediately — but it must be their decision, never yours.
This transitions the phase to `done`, transitions the swamp-club status to
`shipped`, and posts a `complete` lifecycle entry.
39 changes: 28 additions & 11 deletions issue-lifecycle/.claude/skills/issue-lifecycle/references/triage.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,12 +5,12 @@ resuming an issue in the `triaging` phase.

## 1. Create the Model Instance

If it doesn't already exist:
The swamp-club issue must already exist — create it in the swamp-club UI first,
then note its sequential number (e.g. `42`).

```
swamp model create @swamp/issue-lifecycle issue-<N> \
--global-arg issueNumber=<N> \
--global-arg repo=<owner/repo> --json
--global-arg issueNumber=<N> --json
```

**Worktree note:** If you are in a Claude Code worktree (`.claude/worktrees/`),
Expand All @@ -25,6 +25,11 @@ commands in this skill also need `--repo-dir`.
swamp model method run issue-<N> start
```

This fetches the issue from swamp-club via `GET /api/v1/lab/issues/<N>` and
writes the title, body, type, status, and comments to the `context` resource. If
the issue doesn't exist in swamp-club, `start` fails loudly — create the issue
there first.

## 3. Read the Issue Context and Codebase

Read the model output, then explore the codebase.
Expand All @@ -38,7 +43,7 @@ on affected files to see if they were recently changed.

```
swamp model method run issue-<N> triage \
--input type=<bug|feature|regression|unclear> \
--input type=<bug|feature|security> \
--input confidence=<high|medium|low> \
--input reasoning="<your analysis>"
```
Expand All @@ -47,16 +52,28 @@ swamp model method run issue-<N> triage \

- `bug` — something is broken or behaving incorrectly
- `feature` — a request for new functionality or enhancement
- `regression` — a bug where something **previously worked** but is now broken.
Look for signals like: "this used to work", "stopped working after", "worked
in version X", references to recent changes that broke existing behavior, or
git history showing the affected code was recently modified. Regressions get
both `bug` and `regression` labels.
- `unclear` — not enough information to classify confidently
- `security` — security vulnerability, hardening, or compliance work

Add `--input isRegression=true` when the bug previously worked. Look for signals
like: "this used to work", "stopped working after", "worked in version X",
references to recent changes that broke existing behavior, or git history
showing the affected code was recently modified. A regression is still
classified as `type: bug` — `isRegression` is a detail on the classification
record.

**If you cannot classify confidently**, do NOT guess. Ask the human first, or
call `triage` with `confidence=low` and `clarifyingQuestions` populated, then
wait for the human's response before moving on.

Running `triage` automatically:

- Updates the swamp-club issue's `type` field via PATCH
- Transitions the swamp-club status to `triaged`
- Posts a `classified` lifecycle entry with the full classification payload

## 5. Reproduce the Bug

**Bugs and regressions only — skip for features.**
**Bugs and regressions only — skip for features and security issues.**

Before planning a fix, reproduce the issue to confirm the failure mode.

Expand Down
Loading
Loading