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

description

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

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

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:

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

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)

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:

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"
• Only if the spec adds substantive new criteria not already captured in the issue: "Run /sync-issue <number> to update the Gitea issue with the new acceptance criteria". Skip this if the spec merely reformulates what the issue already says into Given/When/Then format.

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.