gh-anton-abyzov-specweave-plugins-specweave-github/commands/specweave-github-update-user-story.md

name, description

name	description
specweave-github-update-user-story	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:

/specweave-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
/specweave-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:

• /specweave-github:sync-epic FS-031 - Sync entire epic (all user stories)
• /specweave-github:create-issue 0031 - Create issue for increment
• /specweave-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