managing-github-issues

Files (8)

• SKILL.md
• evals.json · evals/
• sample-roadmap.md · evals/fixtures/
• sample-todo.md · evals/fixtures/
• unit.test.mjs · evals/fixtures/
• verify.mjs · evals/fixtures/
• github-issues.md · references/
• sync-issues.mjs · scripts/

SKILL.md (first lines)

# Managing GitHub Issues

Turn an established `ROADMAP.md` into a shared, assignable GitHub backlog. The
roadmap is the source of truth; this skill pushes it out to issues. It is the
second half of the triage chain — `triaging-requirements` ranks a backlog into
`ROADMAP.md`, this skill persists those ranked items as issues.

Deterministic, re-runnable work (markdown parse, `gh` calls, dry-run,
write-back, source-doc audit) lives in `scripts/sync-issues.mjs`. The judgment
(what detail to pull, confirming the live run and any cleanup with the user)
lives here.

## The sync pass

Copy this checklist and check off items as you complete them.

```
Sync Progress:
- [ ] 1. Locate ROADMAP.md and resolve the target repo
- [ ] 2. Dry-run — confirm the planned-create set
- [ ] 3. Confirm the live run with the user
- [ ] 4. Apply — create issues, write back refs
- [ ] 5. Re-run dry-run — confirm idempotency (0 to create)
- [ ] 5b. (Optional) Rank in a GitHub Project — `--with-project` (needs `project` token scope)
- [ ] 6. Close the loop — offer source-doc cleanup (confirmation-gated)
```

### Step 1 — Locate ROADMAP.md and resolve the repo

The roadmap is wherever the user points (default: `ROADMAP.md` at the repo
root). Resolve the target GitHub repo:

- Default: infer from the directory containing `ROADMAP.md` via
  `gh repo view --json nameWithOwner` (works for any repo dir, e.g.
  `~/repos/my-app` → `acme/my-app`).
- Override: explicit `--repo owner/name`.

Read the four **open** tables — `## Features`, `## Bugs`, `## Tech Debt`,
`## Chores`. Rows there are the work to sync. `## Done`, `## Skipped`, and
`## Proposed (cut)` are excluded (one-way sync; open items only).

### Step 2 — Dry-run (default-safe)

Run the script with `--dry-run` (the default if neither flag is given):

```
node skills/managing-github-issues/scripts/sync-issues.mjs \
  --dry-run --roadmap <path-to-ROADMAP.md>
```

It prints one planned `gh issue create` per open row, each carrying
`--label "roadmap-id:<id>,<category-label>"`, and a summary
`<N> to create, <M> already backed`. Verify the count matches the open rows and
that Done/Skipped produced nothing. Detail the planned bodies by reading the
script output or its reference.

### Step 3 — Confirm the live run

Creating real issues is an **external side effect**. Do not run `--apply`
without explicit user confirmation. Show the dry-run summary and the target
repo, then ask. Only after the user confirms, run:

```
node skills/managing-github-issues/scripts/sync-issues.mjs \
  --apply --roadmap <path-to-ROADMAP.md>
```

### Step 4 — Apply and write back

`--apply` creates each issue, then rewrites the row's `Sources` cell to append
`owner/repo#<n>` (e.g. `acme/widgets#42`). That write-back is the
two-way link and the idempotency signal.

### Step 5 — Confirm idempotency

Re-run the dry-run. It should now report `0 to create` — every open row is
detected via its `roadmap-id:<id>` label / written-back `Sources` ref. If any
row still shows as "to create", investigate (missing label, parse miss) before
proceeding.

### Step 5b — Rank in a GitHub Project (optional, `--with-project`)

Plain GitHub issues have **no native priority or rank field**. To make the
roadmap's `impact×urgency` ranking visible and sortable in GitHub (the
GitHub-prescribed mechanism), pass `--with-project`. This ensures one Project
(V2) for the repo (idempotent; default title `<repoName> Roadmap`, override with
`--project <number>` or `--project-title <title>`), adds each open issue to it,
and sets a `Priority` single-select from the score buckets:

| Score | Priority |
|---|---|
| ≥ 6 | High |
| 3–5 | Medium |
| ≤ 2 | Low |

```
node skills/managing-github-issues/scripts/sync-issues.mjs \
  --apply --with-project --roadmap <path-to-ROADMAP.md>
```

**Prerequisite — token scope.** Managing Projects requires the `project` OAuth
scope. If `gh project` fails with `missing required scopes [read:project]`, the
user must run `gh auth refresh -s project` first. This is a user-auth action;
the script will not do it.

**Manual order is UI-only.** The `Priority` field is sortable, but the exact
1–N drag-order is set in the Project UI, not via `gh` — `ROADMAP.md` remains the
authoritative total order. Idempotent: re-running adds nothing new and
re-applies `Priority`.

### Step 6 — Close the loop: source-doc cleanup (confirmation-gated)

Once the roadmap is current (re-run reports `0 to create`), the legacy planning
docs named in the roadmap's `sources:` frontmatter are redundant. The script
audits them:

```
node skills/managing-github-issues/scripts/sync-issues.mjs \
  --check-cleanup --roadmap <path-to-ROADMAP.md>

From hierovision/ai-framework, MIT.

More from hierovision/ai-framework