Implement GitHub Issue
Implement a feature or fix based on a GitHub issue, following project standards.
Input
Primary input: the issue number or URL.
Optional last parameter: -- <additional context>
Interpret $ARGUMENTS as one of:
<issue-number><issue-url><issue-number> -- <additional context><issue-url> -- <additional context>
Use any additional context as execution guidance while still following the issue requirements.
Process
Step 1: Understand the Issue
gh issue view <ISSUE_NUMBER> --json number,title,body,labels,assignees,milestone,state,comments
Parse: title, requirements, acceptance criteria, labels, sub-issues, comments, and linked work.
If labels are missing, add appropriate ones with gh issue edit.
Step 2: Assess Readiness
Flag for user input if: vague acceptance criteria, discovery label, unanswered questions, scope too large, or dependencies incomplete.
Step 3: Plan and Validate Approach
Create a task list with TodoWrite. Fold any optional additional context into the plan. Present the approach to the user:
- Files to create or modify
- Libraries, APIs, or services to use
- Where configuration changes live
- Key design decisions
- What will NOT change (scope boundaries)
If the issue includes Implementation Constraints (from forge-create-issue), follow those guardrails.
Get user confirmation via AskUserQuestion before coding.
Step 4: Create Feature Branch
git fetch origin
git checkout $(git symbolic-ref refs/remotes/origin/HEAD | sed 's@^refs/remotes/origin/@@')
git pull
git checkout -b <type>/<issue-number>-<brief-description>
Step 5: Implement
Read AGENTS.md first. Follow project conventions strictly.
Pre-flight checks — before writing feature code:
- Run code generators (GraphQL codegen, OpenAPI, protobuf) and verify types exist
- Grep for where config is consumed before placing new config values
- Verify external services and APIs are accessible
- Confirm new environment variables are set
As you code:
- Follow project lint/format/type conventions
- Check for duplication — extract shared logic
- Keep functions focused — split if growing too large
- Look for existing patterns before writing new code
- Run tests after each commit, not just at the end
- When writing tests, verify assertions match actual output immediately
Commit granularly after each logical unit of work:
git add <files>
git commit -m "<type>(<scope>): <description>
<body>
Refs #<ISSUE_NUMBER>"
Step 6: Pattern Consistency Audit
If you changed a pattern (error handling, component structure, API convention), search for ALL files using that pattern and update them too:
grep -rn "<pattern>" src/
Step 7: Update Documentation
If behavior changed, update:
docs/*.md— architecture, API, development guidesCHANGELOG.md— user-facing changes only, plain language, bold feature namesAGENTS.md— if conventions or patterns changed- Code comments — only where logic isn't self-evident
Step 8: Quality Gates
Run all project quality checks (discover from AGENTS.md or package.json): lint, format, type check, tests. Run coverage for substantial changes. Fix issues and commit fixes.
Step 9: Push and Create PR
git push -u origin <branch-name>
Create PR with conventional commit title format. Include: summary closing the issue, list of changes, test plan checklist, and quality checklist.
If the implementation requires manual deployment steps (env vars, infra changes, Docker config, migrations), add a prominent > [!WARNING] block at the top of the PR body.
Step 10: Summary
Report: branch name, PR link, commits made, files changed, tests added, docs updated, follow-up items.
Guidelines
- Read AGENTS.md first — understand project-specific requirements
- Explore before coding — understand existing patterns
- Small commits — one logical change each
- Test as you go — don't defer testing to the end
- Ask when unsure — better to clarify than implement wrong
- Don't scope creep — implement what the issue asks, nothing more
- Keep TodoWrite in sync with progress
Sub-Issue Handling
If the issue has sub-issues, treat each as a separate TodoWrite task. Close sub-issues as you complete them — GitHub automatically updates parent progress.
Related Skills
After implementing: Use forge-reflect-pr to self-review before requesting review.
Example Usage
/forge-implement-issue 123
/forge-implement-issue 123 -- keep the diff minimal and prefer existing UI patterns
/forge-implement-issue https://github.com/owner/repo/issues/123