# retrospective-sync

> Syncs retrospective data to GitHub Project board and generates MD documentation. Use at the end of a retrospective session.

- Author: Boudy de Geer
- Repository: boudydegeer/scrum-claude
- Version: 20251222052721
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-07
- Source: https://github.com/boudydegeer/scrum-claude
- Web: https://mule.run/skillshub/@@boudydegeer/scrum-claude~retrospective-sync:20251222052721

---

---
name: retrospective-sync
description: Syncs retrospective data to GitHub Project board and generates MD documentation. Use at the end of a retrospective session.
---

# Retrospective Sync Skill

Generates retrospective documentation as MD files and optionally syncs to a dedicated GitHub Project board.

## When to Use

Invoke this skill at the end of a retrospective session (Step 8 of sprint-retro-flow) to:
1. Generate a permanent MD record of the retrospective
2. Create/update an item in the retrospectives GitHub board (if configured)

## Prerequisites

Collect this data before invoking:
- Sprint number and date
- Metrics: velocity, stories completed, bugs found
- Sentiment (positive/neutral/negative)
- "What went well" items
- "What didn't go well" items
- Root cause analysis findings
- Action items with GitHub issue IDs
- Notes from each participating agent

## Configuration

Configuration is optional. If not found, the skill will prompt the user.

In `.scrum-claude.json`:
```json
{
  "retrospective": {
    "boardId": "PVT_xxxx",
    "docsPath": "docs/retrospectives",
    "fields": {
      "sprint": "Sprint",
      "date": "Date",
      "sentiment": "Sentiment",
      "velocity": "Velocity",
      "storiesCompleted": "Stories Completed",
      "actionItemsTotal": "Action Items",
      "actionItemsCompleted": "Actions Done",
      "mdLink": "Doc Link"
    }
  }
}
```

## Workflow

### Step 1: Check Configuration

Read `.scrum-claude.json` and check for `retrospective` section.

If NOT found, prompt the user:
```
No retrospective configuration found.
What would you like to do?

1. Configure board and docs path (full setup)
2. Configure docs path only (no GitHub sync)
3. Skip saving (this time only)
```

For options 1-2, guide interactive setup and save to `.scrum-claude.json`.

### Step 2: Generate MD File

Use the template from `templates/retro.md` to generate the retrospective document.

Save to: `{docsPath}/sprint-{N}-retro.md`

Ensure the directory exists, create if needed.

### Step 3: Sync to GitHub Board (if configured)

Only execute if `boardId` is configured and not empty.

**3.1 Check for existing item:**
```bash
gh project item-list {boardId} --format json | jq '.items[] | select(.content.title | contains("Sprint {N}"))'
```

**3.2 Create or update item:**

If NOT exists:
```bash
gh project item-create {boardId} --title "Sprint {N} Retrospective" --body "Retrospective for Sprint {N}"
```

If exists, get the item ID for updates.

**3.3 Update fields:**
```bash
# Get field IDs first
gh project field-list {boardId} --format json

# Update each field
gh project item-edit --project-id {boardId} --id {itemId} --field-id {fieldId} --text "{value}"
```

Fields to update:
- Sprint number
- Date
- Sentiment emoji (😀/😐/😞)
- Velocity
- Stories completed (X/Y format)
- Action items total count
- Action items completed count
- Link to MD file (relative path or GitHub URL)

### Step 4: Report Results

Output summary:
```
✅ Retrospective documented:
   - MD file: docs/retrospectives/sprint-5-retro.md
   - GitHub board: [item updated/created] (if applicable)
   - Action items tracked: 3 total, 1 completed
```

## Updating Action Item Status

When invoked for a NEW retrospective, also check previous retrospectives' action items:

1. Query GitHub for issues with label "retro-action"
2. Count open vs closed
3. Update previous board items' "Actions Done" field if changed

## Error Handling

- If `gh` command fails, log error but don't fail the entire skill
- If MD write fails, this IS a critical error - report and stop
- If board sync fails, still save MD and report partial success