/github-update-user-story

description: Update GitHub issue for user story with proper ACs and tasks

Update User Story GitHub Issue

**Purpose**: Update an existing GitHub issue for a user story to include:

• ✅ Checkable acceptance criteria (GitHub task checkboxes)
• ✅ Task connections (links to increment tasks)
• ✅ Proper formatting and status

**Usage**:

sw-github:update-user-story FS-031 US-004

**What It Does**:

1. **Finds user story file**: `.specweave/docs/internal/specs/{project}/FS-031/us-004-*.md` 2. **Parses content**:

• User story description (As a... I want... So that...)
• Acceptance criteria with completion status
• Tasks from increment tasks.md

3. **Finds existing GitHub issue**: Searches for `[FS-031][US-004]` or `[FS-031 US-004]` 4. **Updates issue body**: Replaces with properly formatted content including:

• Checkable ACs
• Task connections
• Status and progress

**Arguments**:

• `featureId` - Feature ID (e.g., `FS-031`)
• `userStoryId` - User Story ID (e.g., `US-004`)

**Example**:

# Update US-004 in FS-031
sw-github:update-user-story FS-031 US-004

# Output:
# 🔍 Finding user story: FS-031/US-004
#    📄 Found: .specweave/docs/internal/specs/default/FS-031/us-004-bidirectional-status-sync.md
# 🔍 Searching for existing GitHub issue...
#    🔗 Found issue #501: [FS-031][US-004] Bidirectional Status Sync
# 📝 Building updated issue body...
#    ✅ 6 acceptance criteria (4 completed)
#    ✅ 6 tasks (3 completed)
# 🚀 Updating GitHub issue #501...
#    ✅ Updated successfully!
#    🔗 https://github.com/owner/repo/issues/501

**What Gets Updated**:

**Feature**: [FS-031](../../_features/_archive/FS-031/FEATURE.md)
**Status**: complete
**Priority**: P1
**Project**: default

---

## User Story

**As a** PM
**I want** status changes in external tools to sync back to SpecWeave
**So that** both systems stay in sync without manual updates

📄 View full story: [`us-004-bidirectional-status-sync.md`](...)

---

## Acceptance Criteria

Progress: 4/6 criteria met (67%)

- [x] **AC-US4-01**: SpecWeave status change triggers external update (P1, testable)
- [x] **AC-US4-02**: External issue close triggers SpecWeave prompt (P1, testable)
- [x] **AC-US4-03**: External issue reopen triggers SpecWeave prompt (P2, testable)
- [x] **AC-US4-04**: Sync logs include timestamp and reason (P2, testable)
- [ ] **AC-US4-05**: Failed syncs retry with exponential backoff (P2, testable)
- [ ] **AC-US4-06**: Sync works for GitHub, JIRA, and ADO (P1, testable)

---

## Implementation Tasks

Progress: 3/6 tasks complete (50%)

**Increment**: [0031-external-tool-status-sync](../../increments/0031-external-tool-status-sync/)

- [x] [T-008: Create Status Sync Engine (Core)](../../increments/0031/tasks.md#t-008-create-status-sync-engine-core)
- [x] [T-009: Implement GitHub Status Sync](../../increments/0031/tasks.md#t-009-implement-github-status-sync)
- [x] [T-010: Implement JIRA Status Sync](../../increments/0031/tasks.md#t-010-implement-jira-status-sync)
- [ ] [T-011: Implement ADO Status Sync](../../increments/0031/tasks.md#t-011-implement-ado-status-sync)
- [ ] [T-018: Add Sync Event Logging](../../increments/0031/tasks.md#t-018-add-sync-event-logging)
- [ ] [T-021: Error Handling & Retry Logic](../../increments/0031/tasks.md#t-021-error-handling-retry-logic)

---

🤖 Auto-synced by SpecWeave User Story Sync

**When to Use**:

• ✅ After completing increment implementation (update task statuses)
• ✅ After modifying acceptance criteria
• ✅ When GitHub issue is missing proper formatting
• ✅ When you want to refresh issue content from living docs

**Related Commands**:

• `sw-github:sync-epic FS-031` - Sync entire epic (all user stories)
• `sw-github:create-issue 0031` - Create issue for increment
• `sw-github:sync 0031` - Two-way sync for increment

---

Implementation

**File**: `plugins/specweave-github/lib/user-story-content-builder.ts`

**Workflow**: 1. Parse user story file with `UserStoryContentBuilder` 2. Search GitHub for existing issue (title pattern matching) 3. Build rich issue body with checkable ACs and task links 4. Update issue via `gh issue edit` with new body

**Error Handling**:

• ✅ Graceful fallback if user story file not found
• ✅ Clear error if GitHub issue doesn't exist
• ✅ Validation of required fields (epic, status, etc.)

---

Execution

When user runs this command, the Claude Code assistant should:

1. Extract `featureId` and `userStoryId` from command arguments 2. Find user story file in living docs (search all projects) 3. Use `UserStoryContentBuilder` to parse and build issue body 4. Search for existing GitHub issue using `gh issue list --search` 5. Update issue using `gh issue edit --body` 6. Report success with issue URL

**Tech Stack**:

• TypeScript (UserStoryContentBuilder class)
• GitHub CLI (`gh issue list`, `gh issue edit`)
• YAML frontmatter parsing
• Markdown formatting

**Testing**:

• Test with FS-031/US-004 (bidirectional status sync)
• Verify ACs are checkable
• Verify tasks link to correct increment tasks.md
• Verify progress percentages are correct