initiative/.claude/commands/integrate-issue.md

---
description: Fetch a Gitea issue, identify the affected feature spec(s), and integrate the issue's requirements into the spec. For new features, hands off to /speckit.specify.
---

## User Input

```text
$ARGUMENTS
```

You **MUST** provide an issue number as the argument (e.g. `/integrate-issue 6`). If `$ARGUMENTS` is empty or not a valid number, ask the user for the issue number.

## Prerequisites

1. Verify the `GITEA_TOKEN_ISSUES` environment variable is set:

```bash
test -n "$GITEA_TOKEN_ISSUES" && echo "TOKEN_OK" || echo "TOKEN_MISSING"
```

If missing, tell the user to set it:
```
export GITEA_TOKEN_ISSUES="your-gitea-personal-access-token"
```
Then abort.

2. Parse the git remote to extract the Gitea API base URL, owner, and repo:

```bash
git config --get remote.origin.url
```

Expected format: `ssh://git@<host>:<port>/<owner>/<repo>.git` or `https://<host>/<owner>/<repo>.git`

Extract:
- `GITEA_HOST` — the hostname
- `OWNER` — the repo owner/org
- `REPO` — the repo name (strip `.git` suffix)
- `API_BASE` — `https://<GITEA_HOST>/api/v1`

## Execution

### Step 1 — Fetch the issue

```bash
curl -sf -H "Authorization: token $GITEA_TOKEN_ISSUES" "$API_BASE/repos/$OWNER/$REPO/issues/<NUMBER>"
```

Extract from the JSON response:
- `title` — the issue title
- `body` — the issue body (markdown)
- `labels` — array of label names (if any)

If the API call fails or returns no issue, abort with a clear error.

### Step 2 — Fetch issue comments (if any)

```bash
curl -sf -H "Authorization: token $GITEA_TOKEN_ISSUES" "$API_BASE/repos/$OWNER/$REPO/issues/<NUMBER>/comments"
```

If comments exist, include them as additional context (they may contain clarifications or requirements discussed after the issue was created).

### Step 3 — Route: new feature or existing feature?

List the existing feature specs by reading the `specs/` directory:

```bash
ls -d specs/*/
```

Present the issue summary and existing specs to the user. Ask:

**"Does this issue belong to an existing feature, or is it a new feature?"**

Present options:
- Each existing spec as a numbered option (show spec name and one-line description from CLAUDE.md or the spec's overview)
- A "New feature" option

If the user selects **New feature**, compose the feature description from the issue content (title + body + comments) and hand off to `/speckit.specify`. Stop here.

If the user selects an **existing spec**, continue to Step 4.

### Step 4 — Read the affected spec

Load the selected spec file. Identify the sections that the issue's requirements affect:
- Which user stories need updating?
- Which requirements (FR-NNN) need adding or modifying?
- Which acceptance scenarios change?
- Are new edge cases introduced?

Present your analysis to the user:
- **Stories affected**: list the story IDs/titles that need changes
- **New stories needed**: if the issue introduces behavior not covered by any existing story
- **Requirements to add/modify**: list specific FR numbers or new ones needed

Ask the user to confirm or adjust the scope.

### Step 5 — Draft spec changes

For each affected section, draft the specific changes:

- **Modified stories**: show the before/after for acceptance scenarios
- **New stories**: write them in the spec's format (matching the existing story naming convention — e.g., `**Story HP-7**` for combatant-state, `**Story A4**` for combatant-management)
- **New/modified requirements**: write them with the next available FR number
- **New edge cases**: add to the relevant edge cases section

For per-topic specs (003-combatant-state, 004-bestiary), place changes in the correct topic section.

### Step 6 — Preview and confirm

Show the user a complete preview of all changes:
- Which file(s) will be modified
- The exact additions/modifications (as diffs or before/after blocks)

Ask for confirmation before writing.

### Step 7 — Write changes

On confirmation:
- Write the updated spec file(s)
- Report what was changed (sections touched, stories added/modified, requirements added)

### Step 8 — Suggest next steps

Report completion and suggest next steps based on scope:

- **Straightforward change** (1-2 stories, clear acceptance scenarios): "Implement the changes and commit"
- **Larger change** (multiple stories, cross-cutting concerns): "Use `rpi-research` to investigate the affected code, then `rpi-plan` to create a phased implementation plan, then `rpi-implement` to execute it"
- **Complex or ambiguous change**: "Run `/speckit.clarify` to resolve remaining ambiguities before implementing"
- Always: "Run `/sync-issue <number>` to update the Gitea issue with the new acceptance criteria"

## Behavior Rules

- Never modify the issue on Gitea — this is a read-only operation on the issue side.
- Always preview before writing spec changes — never write without user confirmation.
- Include comment authors in the context so requirements can be attributed.
- If the issue body is empty, warn the user but still proceed with just the title.
- Strip HTML tags from the body/comments if present (Gitea sometimes includes rendered HTML).
- Use `curl` for all API calls — do not rely on `gh` CLI.
- Match the existing spec's naming conventions for stories, requirements, and structure.
- When adding to per-topic specs (003, 004), place content in the correct topic section — do not create new top-level sections unless the change introduces an entirely new topic area.
- Increment FR/SC numbers from the highest existing number in the spec.