feature-impact-ranking

feature-impact-ranking

You're producing an "N most impactful features" ranking for the project, and you'll mutate the repo as a side effect — every item that surfaces gets either a resurface comment on its existing issue or a new Feature issue if no matching one exists. Output: a markdown report the human can read for the synthesized reasoning.

Always do first: load context

Read .claude/project.yaml. You need:

• project.repo — split into <owner>/<repo>
• github.issue_types.feature — the org-level Feature type node ID (used when filing net-new)
• github.milestones — the allowed milestone list (highest urgency first, conventionally)
• github.project_board.* — project board IDs + status field + status options (for board placement, if applicable)
• product.prd — PRD path (for canonical priority signal)
• github.token_env_var — the env var holding the GitHub token

If .claude/project.yaml doesn't exist, stop and surface — direct the user to run /bootstrap-project first.

Args

• First positional arg: N — number of top features to surface
  • Default: 5 (weekly "what next" scan)
  • Use 10 for a quarterly-ish planning view
  • Don't go below 3 or above 15

Context to load

• Repo issues — use the GitHub MCP tools (mcp__github__*) per CLAUDE.md § "GitHub tooling"
• PRD at product.prd — read the Functional Requirements (with P0/P1 priority) and Non-Functional Requirements for canonical priority signal
• Milestones from github.milestones — treat their listed order as urgency (manifest convention: highest urgency first)
• Project board lanes (if github.project_board.id is set): Backlog / Ready / In Progress / In Review / Done
• Issue types: Task / Bug / Feature (org-level types, not labels)
• Issue dependencies — fetch via mcp__github__issue_read (method: "get") and look at issue_dependencies_summary.blocked_by
• Provenance label: impact-ranking — apply to every issue this skill touches (existing or new). If the label doesn't yet exist in the repo, create it before tagging.

Mutation flow (per top-N item)

For each item in the top-N ranking, you MUST:

1. Search for an existing issue that already covers this work. Use mcp__github__search_issues with broad keywords from the feature (scope to repo:<owner>/<repo> in the query), then inspect titles + bodies of the top hits. Be liberal in considering matches — if 80% of the scope overlaps, treat it as the same feature (don't split). Also scan closed issues for cases where something was deferred or punted.
2. If a match exists (the common case for an established roadmap):
   • Post a comment on that issue via mcp__github__add_issue_comment with the resurface rationale (see comment template below)
   • Add the impact-ranking label via mcp__github__issue_write (method: "update", labels: [...existing, "impact-ranking"] — fetch existing first via issue_read since MCP replaces the full label set)
   • Do NOT create a duplicate issue
3. If no match exists (genuinely net-new idea):
   • Create a new issue via mcp__github__issue_write (method: "create")
   • Type: Feature — set via the updateIssueIssueType GraphQL mutation after creation, using the type ID from github.issue_types.feature
   • Milestone: pick the closest fit from the milestone list
   • Labels: impact-ranking plus anything else applicable
   • Body: same shape as the comment template, expanded to issue form (problem, why now, scope, acceptance criteria)
   • Do NOT self-assign — leave the assignee field empty so it surfaces in Backlog as a triage candidate
   • Prefer running the spec-issue-file skill if you want the full metadata pipeline (type + milestone + board placement) applied at create time

For cut-list items: do not mutate. The cut list exists only to give the human context on what didn't make the cut and why.

Comment template (for resurfaces)

## Resurfaced by impact-ranking — YYYY-MM-DD

**Rank in this run: #X of N.**

<one paragraph from the per-item reasoning — anchored in PRD or
user-flow consequences, not vague>

_Posted by the `feature-impact-ranking` skill. To exclude this issue
from future runs, remove the `impact-ranking` label._

What to produce (the markdown report)

1. TL;DR — one or two sentences. The single highest-leverage action this run. Include any cross-cutting observations (e.g. a meta-blocker that gates several top items).
2. Already in flight — top contenders currently in open PRs. Note them but don't include them in the ranking.
3. Top N ranked — for each:
   • Issue number + title (with link)
   • Type, milestone, scope (small / medium / large)
   • Why high-impact: short paragraph anchored in the PRD or user-flow consequences. Don't be vague — point to the specific functional requirement or the user pain it addresses.
   • Mutation outcome: "commented on existing issue #N" OR "created new issue #N"
4. Cut list of min(N, 8) runners-up with one-line "didn't make the cut because…" reasons.
5. Critical path — if there's a meta-blocker (one issue that gates several top items), call it out at the end with a sequenced plan including parallel paths the human can pursue while the meta-blocker is unresolved.

How to score

Anchor primarily on:

1. PRD priority — P0 outranks P1, which outranks anything not in the PRD
2. Milestone proximity — earlier-listed milestones in github.milestones are higher impact for now than later-listed ones
3. User-visible value — does this change what users see/feel, or is it infrastructure? Both can be high impact, but bias toward user-visible when otherwise equal
4. Unblocking effect — does shipping this unblock 2+ other items? That's a multiplier

De-prioritize:

• Things already in open PRs (mention them but exclude from the ranking)
• Pure refactors with no user-visible benefit unless they unblock something
• Issues with question label (those are waiting on a human, not on engineering)
• Issues with deferred label (explicitly deprioritized — leave alone)

Length and voice

• Target: under 1500 words for N=10, under 800 for N=5
• Casual, em-dashes (—), no corporate-speak, dry observational humor welcome
• If something's a P0 PRD requirement, just say so — don't restate the PRD at length

Final report format

Markdown, paste-ready into a GitHub issue comment. End with a short Mutations performed summary so the human can scan what landed in the repo without re-reading the per-item entries:

## Mutations performed
- Commented + labeled #N (rank 1)
- Commented + labeled #N (rank 2)
- Created new issue #N (rank 5) — Feature, milestone <name>
- ...