tickets-migration

name	tickets-migration
description	Step-by-step process for migrating a project from a TICKETS.md file to GitHub Issues. Use when a project has an existing TICKETS.md and a GitHub remote and you want to convert to GitHub Issues for token-efficient tracking.

Tickets Migration: TICKETS.md → GitHub Issues

This skill guides the one-time migration of a project's ticket tracking from a TICKETS.md flat file to GitHub Issues.

---

When to Use

• The project has a docs/TICKETS.md (or similar flat-file ticket tracker)
• The project has a GitHub remote (git remote -v shows a github.com URL)
• The goal is to reduce per-session token cost of loading all ticket context

---

Prerequisites

Before starting, verify:

gh auth status          # must be authenticated
git remote -v           # must show a github.com remote

If gh is not authenticated, stop and ask the user to run gh auth login.

---

Step 1 — Identify Thematic Sections and Active Tickets

Read docs/TICKETS.md and extract:

1. Thematic section headings (e.g., "New Features", "Quality & Hardening", "Contacts") — these become labels
2. Active tickets — all tickets with status other than Done
3. Done/pruned tickets — do NOT migrate; they stay as historical record
4. Dependency relationships — which tickets depend on which others

Create in dependency order: tickets with no dependencies first, then tickets that reference them (so #N refs are valid when you write the dependent issue body).

---

Step 2 — Create GitHub Labels

Create two sets of labels:

Thematic labels (one per section heading — convert to lowercase, replace spaces with hyphens or shorten):

gh label create "feature" --color "0075ca"
gh label create "planning" --color "e4e669"
gh label create "quality" --color "d93f0b"
gh label create "contacts" --color "0e8a16"
gh label create "infrastructure" --color "5319e7"
# Add more as needed for this project's sections

Status labels (always the same set):

gh label create "proposed" --color "ededed"
gh label create "ready" --color "c2e0c6"
gh label create "in-progress" --color "fbca04"
gh label create "blocked" --color "b60205"

Use --force to skip errors if a label already exists.

---

Step 3 — Create GitHub Issues

For each active ticket, create a GitHub Issue using this body template:

> Migrated from TICKET-NNNN · detected_by: <value> · <date>

## Problem
<problem_statement>

## Approach
<intended_approach as bullet list>

## Dependencies
Depends on: #N — reason   (or "—" if none)
*(note if a dependency was a TICKETS.md ticket that is already Done/pruned)*

## Acceptance Criteria
- [ ] criterion 1
- [ ] criterion 2

## Testing
- step 1
- step 2

## Logbook
<logbook_links or "—">

Use gh issue create:

gh issue create \
  --title "<title>" \
  --label "<thematic>,<status>" \
  --body "$(cat <<'EOF'
...body...
EOF
)"

Title: Use the original ticket title directly — no TICKET-NNNN: prefix. The old ID is preserved in the issue body (> Migrated from TICKET-NNNN) for searchability and logbook traceability.

Dependency resolution:

• If a dependency is another active ticket being migrated: create the parent issue first, then use #N in the child's body
• If a dependency is a Done/pruned ticket: note it inline as "(TICKET-NNNN was a prerequisite but is now complete)"

---

Step 4 — Archive TICKETS.md

Replace docs/TICKETS.md with a pointer file:

# Tickets

Tickets are now tracked as GitHub Issues:
https://github.com/<owner>/<repo>/issues

**Last TICKET-NNNN used before migration:** TICKET-XXXX (migrated YYYY-MM-DD)
**Next issue number at time of migration:** #N (GitHub assigns automatically)

---

## Agents

Use `gh issue create` to file new issues. See the `tickets-and-logbook` skill for format and workflow.

[include the quick gh command reference from the tickets-and-logbook skill]

---

## Label Reference

**Thematic:** `feature` · `planning` · `quality` · ... (list project's labels)

**Status:** `proposed` · `ready` · `in-progress` · `blocked`
*(no label for done — just close the issue)*

---

## Migration Notes

- Active tickets migrated to GitHub Issues #N–#N on YYYY-MM-DD.
- Done/pruned tickets were not migrated — historical record below.

---

## Pruned Tickets (Completed — historical record)

| ID | Title | Completed |
| --- | --- | --- |
| TICKET-NNNN | ... | YYYY-MM-DD |

Keep docs/LOGBOOK.md unchanged. Future logbook entries reference issues as #N instead of TICKET-NNNN.

---

Step 5 — Commit and Push

git add docs/TICKETS.md
git commit -m "chore: migrate tickets to GitHub Issues, archive TICKETS.md"
git push

---

Step 6 — Verify

gh issue list --limit 50    # confirm all active tickets are present
gh label list               # confirm all labels exist

Spot-check 2–3 issues to confirm:

• Body contains the original problem statement and acceptance criteria
• Dependency #N references resolve to real open issues
• Labels are correct

---

What NOT to Migrate

• Done/pruned tickets — leave them in the TICKETS.md historical table
• The logbook — docs/LOGBOOK.md stays as-is; it is not a ticket tracker

---

After Migration

The tickets-and-logbook skill governs ongoing work. Key differences from the old TICKETS.md workflow:

Old (TICKETS.md)	New (GitHub Issues)
Create ticket by editing TICKETS.md	gh issue create ...
Update status inline	gh issue edit #N --add-label "in-progress" --remove-label "proposed"
Complete ticket by pruning to table	gh issue close #N --comment "Done. Logbook: YYYY-MM-DD entry."
"Next ID: TICKET-NNNN"	GitHub assigns issue numbers automatically
Quick Reference table	gh issue list --label "in-progress"