github-prep

name	github-prep
description	Prepare GitHub issues for implementation. Validate sizing, break oversized work into smaller issues when needed, research external dependencies, enrich the issue body with concrete codebase context, and add a focused implementation prompt.
scopes	["main"]

GitHub Prep

Prepare GitHub issues so the coding agent can execute them cleanly. Four phases: Size -> Research -> Context -> Prompt.

Use the gh CLI for GitHub operations: gh issue view, gh issue edit, gh issue comment, gh issue create, gh pr list, and gh pr view.

Phase 0: Check for Existing Work

Before running any phase, read the issue body and comments for prior prep outputs: context enrichment, implementation prompts, sub-issue breakdowns, or research notes from an earlier prep pass or from a human.

If the issue already has enough context to start implementation confidently, skip prep entirely and implement the work. Do not regenerate prep that already exists.

If only some phases are missing, run only those phases.

Phase 1: Size Check

Fetch the issue with comments and inspect any linked child issues, checklist items, or explicitly referenced follow-up issues. A well-sized issue is completable in a single focused coding session, roughly 1-4 hours of agent work.

Existing sub-issues

If the issue already references child issues or a decomposition plan, read each one for context. Then use judgment:

• Well-scoped and cover the work -> skip splitting and run Phases 2-4 per issue
• Vague or missing detail -> enrich them in Phase 3 instead of creating replacements
• Only cover part of the work -> create additional issues for the missing scope
• Overlap or conflict -> update the parent issue with a cleaner breakdown proposal
• Tracking/meta issue -> treat each child issue as its own prep target

Sizing heuristics

An issue is too large if it touches 3 or more unrelated modules, includes independently shippable backend and frontend work, contains multiple distinct deliverables, or uses language like "refactor entire", "migrate all", or "rewrite".

If oversized, split it into independently shippable GitHub issues and update the parent issue body with the rationale and execution order.

Sub-issue prioritization

When an issue has or produces multiple sub-issues, assign each a priority order based on:

1. Dependency chain: if B depends on A, A comes first.
2. Foundation first: schema, config, shared utilities, and types before feature code.
3. Backend before frontend unless the issue is UI-only.
4. Risk and unknowns first so blockers surface early.
5. Smallest unblocking unit first when work is independent.

For each sub-issue:

• Prefix the title with [1/N], [2/N], and so on
• Add a Depends on: line near the top of the issue body for prerequisite issue numbers
• Add a Priority rationale: line explaining why it is in that position

Phase 2: Research

Research tools, APIs, and services involved in the work. Focus on what the coding agent cannot easily infer from the repo alone.

• Read the issue, comments, and linked docs to identify external technologies involved
• Search the codebase for existing usage patterns; if the technology is already well integrated, note where and move on
• For new or unfamiliar integrations only, read official docs, note version constraints, and capture auth or setup requirements

Append a brief ## Research Notes section to the issue body. Only include information that would materially change implementation. Skip information the agent can discover by reading the code or running help commands.

Phase 3: Context Enrichment

Scan the codebase and ensure the issue has enough context for a coding agent to start without guessing. Append to the issue body, preserving existing content:

• Entry points -> the 2-5 files or functions the agent should start from
• Definition of Done -> checkboxes with objectively verifiable conditions
• Test cases -> 3-5 concrete scenarios covering the happy path and key edges
• Edge cases or gotchas -> only non-obvious ones uncovered while scanning

Do not pad the issue with trivial details the agent can discover immediately from the code.

In-flight work scan

Check for concurrent GitHub work that could affect implementation:

1. List open pull requests in the repo with gh pr list --state open.
2. Check whether any PRs touch the same feature area, files, or issue.
3. If relevant, include:
   • prerequisite PRs the agent should branch from
   • parallel PRs that may cause merge conflicts
   • related issues or PRs that change scope or approach

Only include overlaps that would materially change implementation.

Phase 4: Implementation Prompt

Generate a 1-2 sentence prompt for the coding agent. It must be specific, actionable, and reference concrete file paths, functions, or modules rather than issue jargon.

Formula: [Action verb] [specific change] in [specific location], following [existing pattern or constraint].

Add the prompt to the issue body under ## Implementation Prompt.

Output Summary

After all phases, report concisely:

1. Sizing: well-sized or split into N sub-issues
2. What was added: one-line summary of research notes, context, and test cases
3. Implementation prompt: the final prompt

Notes

• Always append or update the issue body; preserve the original report, screenshots, and human context
• Scan the actual codebase before writing entry points or test cases
• Each sub-issue must be independently mergeable
• If external APIs or services are involved, finish the research phase before writing implementation guidance