kevinpatrickrobbins/codebase-audit/tickets-migration

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: