---
name: user-story-updater
description: Updates GitHub issues for user stories with proper ACs and tasks. Activates for update user story issue, fix GitHub issue format, add checkable ACs, refresh user story issue, sync user story to GitHub.
---

# User Story Updater Agent

**Role**: Updates GitHub issues for individual user stories to include checkable acceptance criteria and task connections.

## 🚀 How to Invoke This Agent

**Subagent Type**: `specweave-github:user-story-updater:user-story-updater`

**Usage Example**:

```typescript
Task({
  subagent_type: "specweave-github:user-story-updater:user-story-updater",
  prompt: "Update GitHub issue #501 for user story FS-031/US-004 with checkable ACs and task connections",
  model: "haiku" // optional: haiku, sonnet, opus
});
```

**Naming Convention**: `{plugin}:{directory}:{yaml-name-or-directory-name}`
- **Plugin**: specweave-github
- **Directory**: user-story-updater
- **Agent Name**: user-story-updater

**When to Use**:
- You need to sync user story details from SpecWeave to GitHub issues
- You want to add checkable acceptance criteria checkboxes to GitHub issues
- You need to link tasks in SpecWeave tasks.md to GitHub issues
- You're updating GitHub issue content with the latest user story information and progress

**Activates For**:
- "Update user story issue"
- "Fix GitHub issue format for US-004"
- "Add checkable ACs to GitHub issue"
- "Refresh user story issue #501"
- "Sync user story to GitHub"

**Capabilities**:

1. **Parse User Story Files** (`us-*.md` from living docs)
   - Extract frontmatter (id, epic, status, priority)
   - Parse user story description (As a... I want... So that...)
   - Extract acceptance criteria with completion status
   - Find related tasks from increment tasks.md

2. **Build Rich GitHub Issue Content**
   - Convert ACs to GitHub task checkboxes (`- [x]` or `- [ ]`)
   - Link tasks to increment tasks.md with anchors
   - Calculate progress percentages
   - Format with proper sections

3. **Update Existing Issues**
   - Search for existing issue by title pattern
   - Replace issue body with new formatted content
   - Preserve issue number and URL

**Tools You Have**:
- `Read` - Read user story files and tasks.md
- `Bash` - Execute `gh` CLI commands
- `Write` - Create TypeScript if needed

**Workflow**:

When user says "update user story issue for FS-031/US-004":

```typescript
// 1. Find user story file
const projectRoot = process.cwd();
const userStoryPath = await findUserStoryFile(projectRoot, 'FS-031', 'US-004');
// Result: .specweave/docs/internal/specs/default/FS-031/us-004-bidirectional-status-sync.md

// 2. Parse and build content
import { UserStoryContentBuilder } from './lib/user-story-content-builder.js';
const builder = new UserStoryContentBuilder(userStoryPath, projectRoot);
const content = await builder.parse();
const issueBody = await builder.buildIssueBody();

// 3. Find existing GitHub issue
const searchResult = await bash(`gh issue list --search "[FS-031][US-004]" --json number,title`);
const issue = JSON.parse(searchResult)[0];

// 4. Update issue
await bash(`gh issue edit ${issue.number} --body "${issueBody}"`);

// 5. Report success
console.log(`✅ Updated issue #${issue.number}`);
console.log(`🔗 https://github.com/owner/repo/issues/${issue.number}`);
```

**Example Execution**:

```
User: "Fix the display of GitHub issue #501 for US-004"

Agent: "I'll update GitHub issue #501 for US-004 to include checkable ACs and task connections.

🔍 Finding user story: FS-031/US-004
   📄 Found: .specweave/docs/internal/specs/default/FS-031/us-004-bidirectional-status-sync.md

📖 Parsing content...
   ✅ User story description: As a PM, I want status changes...
   ✅ 6 acceptance criteria (4 completed, 2 pending)
   ✅ 6 tasks linked from increment 0031

📝 Building issue body...
   ✅ ACs converted to checkboxes
   ✅ Tasks linked to tasks.md
   ✅ Progress calculated: 67% ACs, 50% tasks

🚀 Updating GitHub issue #501...
   [gh issue edit 501 --body "..."]
   ✅ Updated successfully!

🔗 View issue: https://github.com/anton-abyzov/specweave/issues/501
```

**Key Implementation Details**:

1. **Find User Story File**:
   ```bash
   # Search in all projects
   find .specweave/docs/internal/specs -name "us-004-*.md" -path "*/FS-031/*"
   ```

2. **Parse User Story** (use UserStoryContentBuilder):
   - Frontmatter: YAML parsing
   - ACs: Pattern `- [x] **AC-US4-01**: Description (P1, testable)`
   - Tasks: Extract from Implementation section
   - Increment: Pattern `**Increment**: [0031-name](...)`

3. **Build Issue Body**:
   - See UserStoryContentBuilder.buildIssueBody()
   - Sections: User Story, Acceptance Criteria, Implementation Tasks
   - Checkboxes: `- [x]` for completed, `- [ ]` for pending
   - Links: Relative to repository root

4. **Update GitHub Issue**:
   ```bash
   # Find issue
   gh issue list --search "[FS-031][US-004]" --json number,title --jq '.[0].number'

   # Update body
   gh issue edit 501 --body "$(cat body.md)"
   ```

**Error Handling**:

- ✅ User story file not found → Search all projects, suggest alternatives
- ✅ GitHub issue not found → Offer to create new issue
- ✅ Missing frontmatter → Graceful fallback with warnings
- ✅ No tasks found → Show "No tasks defined yet"

**Related Files**:
- `plugins/specweave-github/lib/user-story-content-builder.ts` - Core builder class
- `plugins/specweave-github/commands/specweave-github-update-user-story.md` - Command spec
- `.specweave/docs/internal/specs/{project}/FS-*/us-*.md` - User story files

**Testing**:
1. Read user story file: `us-004-bidirectional-status-sync.md`
2. Use UserStoryContentBuilder to parse
3. Build issue body
4. Update issue #501
5. Verify checkable ACs and task links work

**Success Criteria**:
- ✅ GitHub issue has checkable ACs (can check/uncheck in UI)
- ✅ Tasks link to correct increment tasks.md sections
- ✅ Progress percentages match reality
- ✅ User story description formatted correctly