backlog-sync

Files (1)

• SKILL.md

SKILL.md (first lines)

# Backlog Sync

## Prerequisites

| Platform | CLI / Tool | Check | Install / Configure |
|----------|-----------|-------|---------------------|
| GitHub | `gh` | `gh auth status` | `gh auth login` |
| GitLab | `glab` | `glab auth status` | `glab auth login` |
| Azure DevOps | `az` | `az account show` | `az login && az extension add --name azure-devops` |
| Jira | `curl` + env vars | `echo $JIRA_API_TOKEN` | Set `JIRA_BASE_URL`, `JIRA_USER_EMAIL`, `JIRA_API_TOKEN` |
| Bitbucket | `curl` + env vars | `echo $BITBUCKET_TOKEN` | Set `BITBUCKET_WORKSPACE`, `BITBUCKET_REPO`, `BITBUCKET_TOKEN` |

> Only the CLI for the target platform is required. You do not need all of them.

---

## Active Job Monitoring (CRITICAL)

When creating issues, you MUST create them one by one and report progress.
**Never** batch-create without tracking. After all issues are created, report:
total created, any failures, and the URLs of the new issues.

---

## 1. Platform Detection

Auto-detect the target platform from project files:

| Indicator | Platform |
|-----------|----------|
| `.github/` directory exists | **GitHub** |
| `.gitlab-ci.yml` exists | **GitLab** |
| `azure-pipelines.yml` exists | **Azure DevOps** |
| `JIRA_BASE_URL` env var is set | **Jira** |
| `BITBUCKET_WORKSPACE` env var is set | **Bitbucket** |

If multiple indicators match, ask the user which platform to use.
If none match, ask: "Which issue tracker does this project use?"

---

## 2. Parsing the Story Map

The story map follows the standard format from the Story Mapping skill.
Parse each epic table to extract:

| Field | Source column | Maps to |
|-------|-------------|---------|
| US ID | `US ID` | Issue title prefix |
| Title | `User Story` | Issue title |
| Persona | `Persona` | Label |
| Priority | `Priority` | Label (P1/P2/P3) |
| Acceptance Criteria | `Acceptance Criteria` | Issue body |
| Epic | Table heading (`## Epic N: Name`) | Milestone, parent issue, or label |

Compose the issue title as: `US-NNN: <User Story text>`

Compose the issue body as:

```markdown
## User Story

As a [Persona], I want [action], so that [value].

## Acceptance Criteria

- **Given** [precondition]
  **When** [action]
  **Then** [expected result]

## Metadata

- **Epic:** [Epic Name]
- **Persona:** [Persona ID and Name]
- **Priority:** [P1/P2/P3]
- **T-shirt Size:** [if estimated]
```

---

## 3. Idempotency Guard (CRITICAL)

Before creating any issue, **search for an existing issue with the same US ID**
to avoid duplicates:

```bash
# GitHub
gh issue list --search "US-101" --json number,title --limit 5

# GitLab
glab issue list --search "US-101" --per-page 5

# Azure DevOps
az boards work-item query --wiql "SELECT [System.Id] FROM WorkItems WHERE [System.Title] CONTAINS 'US-101'"
```

For Jira and Bitbucket, use their respective search APIs via `curl`.

If a match is found:
- Report: "US-101 already exists as #<number> — skipping."
- Do NOT create a duplicate. Move to the next story.

---

## 4. Creating Issues by Platform

### GitHub Issues

```bash
gh issue create \
  --title "US-101: Login via SSO" \
  --body "<body markdown>" \
  --label "P1,persona:FieldRep,epic:Authentication"
```

To assign to a milestone (epic): `--milestone "Epic 1: Authentication"`

### GitLab Issues

From jterratsdev/smart-deployment, BSD-3-Clause.

More from jterratsdev/smart-deployment