157 lines
5.1 KiB
Markdown
157 lines
5.1 KiB
Markdown
---
|
|
name: specweave-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**:
|
|
```bash
|
|
/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**:
|
|
```bash
|
|
# 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**:
|
|
|
|
```markdown
|
|
**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
|