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

---
description: Update a Gitea issue with business-level acceptance criteria extracted from the feature spec's user stories.
---

## User Input

```text
$ARGUMENTS
```

You **MUST** provide an issue number as the argument (e.g. `/sync-issue 42`). 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`

3. Locate the spec file. List the available feature specs:

```bash
ls specs/*/spec.md
```

Present the specs to the user and ask which one contains the acceptance criteria for this issue. If only one spec exists, use it automatically.

## Execution

### Step 1 — Read the spec

Load the spec file at `FEATURE_SPEC`. Extract user stories and acceptance scenarios using these patterns:

**Flat specs** (001-combatant-management, 002-turn-tracking):
- Look for the `## User Scenarios & Testing` section
- Each `### ... Story ...` or `**Story ...** ` block
- The **Acceptance Scenarios** numbered list within each story (Given/When/Then format)
- The **Edge Cases** section(s)

**Per-topic specs** (003-combatant-state, 004-bestiary):
- Stories are nested inside topic sections (e.g., `## Hit Points` > `### User Stories` > `**Story HP-1 — ...**`)
- Scan ALL `##` sections for `**Story ...` or `**US-...` patterns
- Extract acceptance scenarios from each story regardless of nesting depth
- Collect edge cases from each topic section's `### Edge Cases` subsection

### Step 2 — Condense into business-level acceptance criteria

For each user story, extract the acceptance scenarios and rewrite them as concise, business-level checkbox items. Group by user story title.

**Transformation rules:**
- Strip Given/When/Then syntax — write as plain outcomes
- Remove implementation details (API names, database references, component names, file paths, config values, tool names)
- Focus on what the user **can do** or **can see**
- Keep each item to one line
- Preserve the grouping by user story for readability

**Example transformation:**

Input (from spec):
```
**Given** no sources are cached, **When** the user clicks the import button in the top bar,
**Then** the stat block side panel opens showing a descriptive explanation, an editable
pre-filled base URL, and a "Load All" button.
```

Output (for issue):
```
- [ ] Clicking the import button opens a panel with a description, editable URL, and "Load All" button
```

Also include edge cases as a separate group if they describe user-facing behavior.

### Step 3 — Fetch the existing issue

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

Extract the current `body` from the response.

### Step 4 — Update the issue body

Merge the acceptance criteria into the existing issue body:

- If the body already has an `## Acceptance Criteria` section, **replace** its contents (everything between `## Acceptance Criteria` and the next `##` heading or end of body).
- If the body does not have an `## Acceptance Criteria` section, insert it after the `## Summary` section (or at the end if no Summary exists).

Preserve all other sections of the issue body unchanged.

The acceptance criteria section should look like:

```markdown
## Acceptance Criteria

### <User Story 1 Title>
- [ ] <criterion from acceptance scenario>
- [ ] <criterion from acceptance scenario>

### <User Story 2 Title>
- [ ] <criterion from acceptance scenario>

### Edge Cases
- [ ] <edge case behavior>
```

### Step 5 — Preview and confirm

Show the user:
- The full updated issue body
- A diff summary of what changed (sections added/replaced)

Ask for confirmation before updating.

### Step 6 — Push the update

On confirmation:

```bash
curl -sf -X PATCH \
  -H "Authorization: token $GITEA_TOKEN_ISSUES" \
  -H "Content-Type: application/json" \
  "$API_BASE/repos/$OWNER/$REPO/issues/<NUMBER>" \
  -d @- <<'PAYLOAD'
{
  "body": "<updated body>"
}
PAYLOAD
```

Report success with the issue URL.

## Behavior Rules

- Never modify the issue title, labels, milestone, or assignees — only the body.
- Always preview before updating — never push without user confirmation.
- If the spec has no user stories or acceptance scenarios, abort with a clear message suggesting the user run `/speckit.specify` first.
- Acceptance criteria must be business-level. If you find yourself writing implementation details, rewrite at a higher level of abstraction.
- Do NOT sync when the issue's existing acceptance criteria already capture the same requirements as the spec. The spec's Given/When/Then format is not needed in the issue — if the only difference is formatting, skip the sync and tell the user the criteria already align.
- Use `curl` for all API calls — do not rely on `gh` CLI.
- Always use HEREDOC for the JSON payload to handle special characters in the body.
- Escape double quotes and newlines properly in the JSON body.