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
20 changes: 10 additions & 10 deletions .claude/skills/issue-lifecycle/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -45,14 +45,14 @@ reference file.
Each phase has detailed instructions in a reference file. Read only the
reference you need for the current phase.

### Phase 1: Triage (steps 1–5)
### 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: creating the model instance,
fetching issue context from swamp-club, reading the codebase, classifying the
issue, and reproducing bugs.
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.

### Phase 2: Planning (steps 6–9)
### 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
Expand Down Expand Up @@ -97,7 +97,7 @@ but do NOT map to separate swamp-club types:
To review a specific plan version:

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

To see all model data:
Expand Down Expand Up @@ -144,20 +144,20 @@ When a PR has already merged and the lifecycle just needs to be marked done:
```
2. If the phase is `implementing`, link the PR first:
```
swamp model method run issue-<N> link_pr --input url=<PR URL>
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 method run issue-<N> pr_merged
swamp model @swamp/issue-lifecycle method run pr_merged issue-<N>
```
4. If the phase is `releasing`, ship it:
```
swamp model method run issue-<N> ship
swamp model @swamp/issue-lifecycle method run ship issue-<N>
```
5. For quick close-out, `complete` still works from `implementing`, `pr_open`,
or `releasing`:
```
swamp model method run issue-<N> complete
swamp model @swamp/issue-lifecycle method run complete issue-<N>
```

## Key Rules
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -67,7 +67,7 @@ findings:
Then record them:

```
swamp model method run issue-<N> adversarial_review \
swamp model @swamp/issue-lifecycle method run adversarial_review issue-<N> \
--input-file /tmp/findings-issue-<N>.yaml
```

Expand Down Expand Up @@ -111,7 +111,7 @@ When the human gives feedback OR adversarial findings need addressing:
if you want to diff between iterations), then run:

```
swamp model method run issue-<N> iterate \
swamp model @swamp/issue-lifecycle method run iterate issue-<N> \
--input feedback="<human's feedback or adversarial findings>" \
--input summary="..." \
--input dddAnalysis="..." \
Expand All @@ -132,7 +132,7 @@ When the human gives feedback OR adversarial findings need addressing:
```

```
swamp model method run issue-<N> resolve_findings \
swamp model @swamp/issue-lifecycle method run resolve_findings issue-<N> \
--input-file /tmp/resolutions-issue-<N>.yaml
```

Expand All @@ -151,7 +151,7 @@ When the human gives feedback OR adversarial findings need addressing:

6. Only then call `approve`:
```
swamp model method run issue-<N> approve
swamp model @swamp/issue-lifecycle method run approve issue-<N>
```

**The `approve` method will fail** if critical/high findings are unresolved or
Expand Down
16 changes: 8 additions & 8 deletions .claude/skills/issue-lifecycle/references/implementation.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ Read this after the plan is approved and the human says to implement. The
Before writing any code, signal that implementation has begun:

```
swamp model method run issue-<N> implement
swamp model @swamp/issue-lifecycle method run implement issue-<N>
```

This transitions the phase to `implementing` and posts an
Expand Down Expand Up @@ -51,7 +51,7 @@ After the PR is open, record its URL on the lifecycle so the swamp-club record
points to where the fix lives:

```
swamp model method run issue-<N> link_pr --input url=<PR URL>
swamp model @swamp/issue-lifecycle method run link_pr issue-<N> --input url=<PR URL>
```

This writes a `pullRequest-main` resource, transitions the phase to `pr_open`,
Expand Down Expand Up @@ -84,11 +84,11 @@ Check the PR status externally (e.g.,

- **PR merged**: call `pr_merged` to transition to `releasing`
```
swamp model method run issue-<N> pr_merged
swamp model @swamp/issue-lifecycle method run pr_merged issue-<N>
```
- **PR failed** (CI red, changes requested): call `pr_failed` with the reason
```
swamp model method run issue-<N> pr_failed --input reason="CI failed: type check errors"
swamp model @swamp/issue-lifecycle method run pr_failed issue-<N> --input reason="CI failed: type check errors"
```
- **PR still open and passing**: wait and check again later.

Expand All @@ -99,11 +99,11 @@ When in `pr_failed`, diagnose and fix the issue. Then either:
- Push fixes and call `link_pr` again (same or new PR URL) to return to
`pr_open`:
```
swamp model method run issue-<N> link_pr --input url=<PR URL>
swamp model @swamp/issue-lifecycle method run link_pr issue-<N> --input url=<PR URL>
```
- Call `implement` to go back to the implementing phase for major rework:
```
swamp model method run issue-<N> implement
swamp model @swamp/issue-lifecycle method run implement issue-<N>
```

## 5. Ship the Release
Expand All @@ -112,13 +112,13 @@ After `pr_merged` transitions to `releasing`, wait for the release build to
complete. Once the release is out, call `ship`:

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

Optionally pass release metadata:

```
swamp model method run issue-<N> ship --input releaseUrl=<URL> --input releaseNotes="Bug fix release"
swamp model @swamp/issue-lifecycle method run ship issue-<N> --input releaseUrl=<URL> --input releaseNotes="Bug fix release"
```

This transitions the phase to `done`, transitions the swamp-club status to
Expand Down
10 changes: 5 additions & 5 deletions .claude/skills/issue-lifecycle/references/planning.md
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
# Planning Phase

Steps 6–9 of the issue lifecycle. Read this after triage is complete and you're
Steps 5–7 of the issue lifecycle. Read this after triage is complete and you're
ready to generate an implementation plan.

## 6. Generate an Implementation Plan
## 5. Generate an Implementation Plan

Write a single YAML file containing both `steps` and `potentialChallenges` as
top-level keys. The CLI only supports one `--input-file` flag per invocation,
Expand Down Expand Up @@ -38,22 +38,22 @@ Then run the method. The `--input` flags handle scalar values, and
`--input-file` handles the structured data:

```
swamp model method run issue-<N> plan \
swamp model @swamp/issue-lifecycle method run plan issue-<N> \
--input summary="..." \
--input dddAnalysis="..." \
--input testingStrategy="..." \
--input-file /tmp/plan-issue-<N>.yaml
```

## 7. Apply Repo-Specific Planning Conventions
## 6. Apply Repo-Specific Planning Conventions

Read `agent-constraints/planning-conventions.md` at the repo root for
repo-specific planning requirements (documentation checks, test strategy,
analysis conventions, and any additional assessments the repo defines). If it
does not exist, generate the plan based on your codebase analysis and CLAUDE.md
conventions.

## 8. Present the Plan
## 7. Present the Plan

Show the plan to the human, including any assessment findings required by the
repo's planning conventions. Then run adversarial review (see
Expand Down
37 changes: 17 additions & 20 deletions .claude/skills/issue-lifecycle/references/triage.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Triage Phase

Steps 1–5 of the issue lifecycle. Read this when starting a new triage or
Steps 1–4 of the issue lifecycle. Read this when starting a new triage or
resuming an issue in the `triaging` phase.

## Before You Start
Expand All @@ -18,37 +18,34 @@ swamp data get issue-<N> state-main --json
- If the command **fails** (no data found), the model instance hasn't been
created yet — proceed with step 1 below.

## 1. Create the Model Instance
## 1. Start the Lifecycle

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> --json
swamp model @swamp/issue-lifecycle method run start issue-<N> --input issueNumber=<N>
```

**Worktree note:** If you are in a Claude Code worktree (`.claude/worktrees/`),
the worktree is not an initialized swamp repository. Add
`--repo-dir <path-to-main-repo>` to all `swamp` commands, where the main repo is
the parent of the `.claude/worktrees/` directory. All subsequent `swamp`
commands in this skill also need `--repo-dir`.

## 2. Fetch the Issue Context

```
swamp model method run issue-<N> start
```
This uses direct type execution to auto-create the model definition and run
`start` in a single command. The definition is stored in
`.swamp/auto-definitions/` (not `models/`).

> **Warning:** `start` unconditionally resets the phase to `triaging`. Only call
> it once when beginning a new lifecycle. Never use it to resume an in-progress
> issue — it will destroy all progress (classification, plan, approvals).

This fetches the issue from swamp-club via `GET /api/v1/lab/issues/<N>` and
`start` 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.

**Worktree note:** If you are in a Claude Code worktree (`.claude/worktrees/`),
the worktree is not an initialized swamp repository. Add
`--repo-dir <path-to-main-repo>` to all `swamp` commands, where the main repo is
the parent of the `.claude/worktrees/` directory. All subsequent `swamp`
commands in this skill also need `--repo-dir`.

### Auto-assignment

`start` automatically assigns the issue to you in swamp-club. It reads your
Expand All @@ -59,7 +56,7 @@ endpoint, and PATCHes the issue's assignees. Existing assignees are preserved
error, API failure), `start` still succeeds — it logs a warning and continues
with triage.

## 3. Read the Issue Context and Codebase
## 2. Read the Issue Context and Codebase

Read the model output, then explore the codebase.

Expand All @@ -68,10 +65,10 @@ explore this codebase. If it does not exist, start with `CLAUDE.md` and explore
source files related to the issue. Check for regression signals: use `git log`
on affected files to see if they were recently changed.

## 4. Classify the Issue
## 3. Classify the Issue

```
swamp model method run issue-<N> triage \
swamp model @swamp/issue-lifecycle method run triage issue-<N> \
--input type=<bug|feature|security> \
--input confidence=<high|medium|low> \
--input reasoning="<your analysis>"
Expand Down Expand Up @@ -100,7 +97,7 @@ Running `triage` automatically:
- Transitions the swamp-club status to `triaged`
- Posts a `classified` lifecycle entry with the full classification payload

## 5. Reproduce the Bug
## 4. Reproduce the Bug

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

Expand Down
Loading