ghs-issue-implement

Issue Implementation

Implement GitHub issues using parallel worktree-based agents. For simple issues, spawns a single agent per issue. For complex issues, invokes GSD's full planning and execution pipeline — discuss, plan, execute, verify — with wave-based parallelization and fresh context per task.

<context> <execution_context> References: - ../shared/references/gh-cli-patterns.md - ../shared/references/output-conventions.md - ../shared/references/ui-brand.md - ../shared/references/argument-parsing.md - ../shared/references/agent-spawning.md - ../shared/references/implementation-workflow.md - ../shared/references/gsd-integration.md - ../shared/references/edge-cases.md - ../shared/references/state-persistence.md - ../shared/references/checkpoint-patterns.md - ../shared/references/agent-result-contract.md </execution_context>

Purpose: Implement GitHub issues and create PRs. Routes through either the fast path (single-shot agent) or the GSD path (multi-phase pipeline) based on issue complexity.

Shared References

Reference	Path	Use For
Agent spawning	../shared/references/agent-spawning.md	Worktree creation, agent spawning, context budgeting, result contract, bounded retries, cleanup, wave-based execution
GSD integration	../shared/references/gsd-integration.md	GSD detection, complexity routing, command patterns, skill-to-GSD contract, error handling
State persistence	../shared/references/state-persistence.md	State issue lifecycle, reading/writing session state via GitHub Issues
gh CLI patterns	../shared/references/gh-cli-patterns.md	Authentication, repo detection, error handling
Output conventions	../shared/references/output-conventions.md	Status indicators, table formats, summary blocks
Edge cases	../shared/references/edge-cases.md	Rate limiting, content filters, permission errors, bounded retries

The user must have write access to the target repository. </context>

<anti-patterns>

Do NOT	Do Instead	Why
Implement without reading full issue + comments	Fetch issue with --json body,comments and read everything before planning	Misses acceptance criteria, duplicate context, or design decisions discussed in thread
Modify files outside issue scope	Only touch files directly required by the issue — log new discoveries as separate issues	Causes merge conflicts with other agents, introduces unreviewed changes
Skip verification before creating PR	Run tests, lint, and type-check before pushing	Broken PRs waste reviewer time and erode trust in automation
Create PR for incomplete work	Set NEEDS_HUMAN status instead — partial worktree is more useful than a broken PR	Incomplete PRs block the merge queue and confuse reviewers
Pass entire scan/backlog to subagent	Pass only: issue details, repo structure, acceptance criteria, tech stack	Bloats agent context, causes confusion and hallucination
Force GSD on simple issues	Use complexity routing — Low/Medium go fast path, High/Very High go GSD	GSD overhead isn't justified for a typo fix or single-file change
Skip state issue check at start	Read state issue for active blockers and previous attempts	Re-trying known-blocked items wastes time and confuses users
Apply type:* labels without checking they exist	Check existing labels first; create missing ones or fall back to repo defaults	Repos without the GHS label taxonomy will fail on gh issue create --label

</anti-patterns>

Scope Boundary

Only implement what the issue describes. If the agent discovers adjacent problems (outdated deps, missing tests for unrelated code, style inconsistencies), it must not fix them inline. Instead, note them in the PR body under a "Discovered Issues" section so they can be filed separately.

Complexity Routing

Every issue goes through a routing decision before execution. See ../shared/references/gsd-integration.md § Complexity Routing for the full decision matrix.

Decision Flow

1. Check state issue for active blockers on this issue
2. Fetch issue details + analysis comment (if any)
3. Determine complexity:
   a. Analysis comment exists → use its Complexity field
   b. No analysis → estimate from issue body signals
4. Route:
   - Low/Medium → Fast Path (Phase 5a)
   - High/Very High → GSD Path (Phase 5b)
   - User override → respect explicit request

Complexity Signals (when no analysis exists)

Signal	Points Toward
Single file mentioned	Fast path
"typo", "fix", "update" in title	Fast path
1-2 acceptance criteria	Fast path
4+ files mentioned	GSD path
"refactor", "migration", "redesign"	GSD path
Sub-task checklist in body	GSD path
Multiple modules/subsystems affected	GSD path
Architectural decision required	GSD path

When ambiguous, default to fast path. The user can always re-run with /gsd:quick or ask for the GSD path explicitly.

Circuit Breaker

Attempt	Action
1st failure	Re-run agent with error context appended to prompt
2nd failure	Re-run with error + stricter constraints (smaller scope, explicit file list)
3rd failure	Mark NEEDS_HUMAN, preserve worktree, report failure details

After 3 failures on the same issue, stop retrying. The worktree is left in place for manual continuation. See ../shared/references/agent-spawning.md § Bounded Retries.

Context Budget

What to pass to each implementation agent:

Pass	Do Not Pass
{owner}, {repo}, {default_branch}	Other issues in the batch
Issue number, title, body, comments	Full scan/backlog results
Analysis comment (if present from ghs-issue-analyze)	Other agents' output or status
Tech stack detection results	Repository-wide metrics
Worktree path and branch name	Unrelated backlog items
Acceptance criteria extracted from issue	Previous session history
State issue active blockers (for this issue only)	Full state issue contents

<objective> Implement GitHub issues and create PRs with auto-close references.

Outputs:

• PRs created on GitHub for each implemented issue
• Labels updated on implemented issues (status:in-progress)
• Terminal report with implementation results
• State issue updated with session comment
• NEEDS_HUMAN items listed with failure details

Next routing:

• Suggest ghs-merge-prs to merge the created PRs — "To merge: /ghs-merge-prs {owner}/{repo}" </objective>

<required_reading> Read issue analysis comment (if exists) and state issue before implementation. </required_reading>

Input

Four invocation modes — the trigger phrase determines which:

Trigger	Mode	What It Fetches
implement issue #42, fix #42, code issue #42	Single issue	One issue by number
implement all triaged issues	Batch by label	Issues with status:triaged
implement all bugs	Batch by type	Issues with type:bug
owner/repo refresh readme for .NET 10	Create-and-implement	No issue — creates one from description

Rule/Trigger/Example Triples

Rule: A single issue number resolves to single-issue mode. Trigger: User says "implement #42" or "fix issue #42". Example: Fetch #42 (type:bug) -> assess complexity -> route to fast or GSD path -> implement -> PR.

Rule: "all" + a label keyword resolves to batch mode. Trigger: User says "implement all triaged issues" or "implement all bugs". Example: Fetch all matching issues, assess each issue's complexity, group by path (fast vs GSD), execute in parallel within each group.

Rule: User can force a specific path. Trigger: User says "use GSD for #42" or "just quick-fix #42". Example: Override complexity routing and use the requested path regardless of signals.

Rule: A closed issue is skipped unless explicitly requested. Trigger: User says "implement #42" but #42 is closed. Example: Warn the user and skip. If user insists, proceed with a note.

Rule: No issue number + free-form text resolves to create-and-implement mode. Trigger: User says "owner/repo refresh readme" or "owner/repo fix the broken badge". Example: Investigate repo -> create issue with description -> assess complexity -> route -> implement -> PR.

Branch Naming

Branch prefix is determined by the issue's type label:

Type Label	Branch Prefix	Example
type:bug	fix/	fix/42-login-crash
type:feature	feat/	feat/15-dark-mode
type:docs	docs/	docs/18-update-readme
type:hotfix	fix/	fix/99-security-vuln
(no type label)	impl/	impl/50-misc-task

Pattern: {prefix}/{issue-number}-{short-slug} Where {short-slug} = issue title, lowercased, non-alphanumeric replaced with -, truncated to 40 chars.

<process>

Phase 1 — Read State & Fetch Issues

Read state issue (per ../shared/references/state-persistence.md § Reading State):

gh issue list --repo {owner}/{repo} --label "ghs:state" --state open
# Then read the most recent state issue:
gh issue view {state_issue_number} --repo {owner}/{repo} --json body,comments

1. Fetch open state issue via gh issue list (label: ghs:state)
2. Extract active blockers from issue comments → flag blocked issues in plan
3. Extract decisions → apply user preferences
4. Show "Last activity: {date} — {summary}" if recent

Single issue mode:

gh issue view {number} --repo {owner}/{repo} \
  --json number,title,body,labels,comments,assignees,state

Skip if closed (unless user explicitly requests).

Batch mode:

gh issue list --repo {owner}/{repo} --state open --label "{filter_label}" \
  --json number,title,body,labels,comments --limit 50

For each issue, extract:

---

Content truncated.