Implement GitHub Issue

Implement a feature or fix based on a GitHub issue, following project standards.

Input

The issue number or URL will be provided as: $ARGUMENTS

Process

Step 1: Fetch Issue Details

# Get issue details
gh issue view <ISSUE_NUMBER> --json number,title,body,labels,assignees,milestone,state,comments

# Check for sub-issues (tasks in the body with checkboxes)
# Look for patterns like: - [ ] task or - [x] completed task

# Check for linked issues or parent issues
gh api repos/{owner}/{repo}/issues/<ISSUE_NUMBER> --jq '.body'

Step 2: Analyze the Issue

Parse and understand:

1. •Title: What is being requested at a high level
2. •Description: Detailed requirements, acceptance criteria
3. •Labels: Use labels to understand the issue context:
   • •Type labels (bug, feature, enhancement, refactor, performance, security, testing, documentation): What kind of work is this?
   • •Area labels (e.g., area: backend, area: frontend, or project-specific areas): Which parts of the codebase are affected?
   • •Workflow labels (epic, discovery, blocked): Special handling needed?
   • •Priority labels (priority: high, priority: low): How urgent is this?
4. •Sub-issues/Tasks: Checklist items that need to be completed
5. •Comments: Additional context, clarifications, discussions
6. •Linked PRs/Issues: Related work or dependencies

If the issue is missing labels, add appropriate ones before proceeding:

gh issue edit <ISSUE_NUMBER> --add-label "<type-label>" --add-label "<area-label>"

Step 3: Assess Readiness

Evaluate if the issue is ready for implementation. Flag for user input if:

Unclear Requirements:

• •Vague acceptance criteria
• •Missing technical details
• •Ambiguous scope

Discovery Needed:

• •Issue has the discovery label (indicates research/spike work)
• •Issue mentions "spike", "research", "investigate", "explore"
• •Multiple valid implementation approaches
• •Unknown technical feasibility

Missing Information:

• •Referenced designs/specs not available
• •Dependencies on other issues not completed
• •Questions in comments not answered

Scope Concerns:

• •Issue seems too large (should be broken down)
• •Conflicting requirements
• •Out of date with current codebase

If any flags are raised, use AskUserQuestion to clarify before proceeding:

Before implementing, I need clarification on:
1. <specific question>
2. <specific question>

How would you like to proceed?

Step 4: Create Implementation Plan

Using TodoWrite, create a task list:

1. •Break down the issue into discrete tasks
2. •Identify files that need to be created/modified
3. •Plan test coverage
4. •Identify documentation updates needed

Step 5: Create Feature Branch

# Detect the default branch (main, master, develop, etc.)
git symbolic-ref refs/remotes/origin/HEAD | sed 's@^refs/remotes/origin/@@'

# Ensure we're on the latest default branch
git fetch origin
git checkout <default-branch>
git pull origin <default-branch>

# Create feature branch with conventional naming
# Format: <type>/<issue-number>-<brief-description>
# Types: feat, fix, docs, refactor, test, chore
git checkout -b <type>/<issue-number>-<brief-description>

Branch naming examples:

• •feat/123-add-user-authentication
• •fix/456-resolve-memory-leak
• •docs/789-update-api-reference

Step 6: Implement the Solution

Follow CLAUDE.md guidelines strictly:

Code Quality:

• •Follow the project's CLAUDE.md for architecture and layering conventions
• •Run the project's lint/format commands (check CLAUDE.md or package.json scripts)
• •Follow the project's type strictness conventions
• •No hardcoded secrets - use environment variables

Modularity & Reusability:

• •Extract shared logic: If the same logic appears in 2+ places, extract it to a utility function in lib/
• •Keep components focused: Each component should do one thing well. If a file grows large (>200 lines) or handles multiple concerns, split it
• •Use named types: Define types for function params/returns at API boundaries (3+ properties, used in multiple places)
• •Centralize constants: Colors, thresholds, magic numbers → extract to shared constants or utility functions
• •Look for existing patterns: Before writing new code, check if similar functionality exists that can be reused or extended

Testability:

• •Pure functions: Extract logic into pure functions that are easy to unit test (no side effects, predictable outputs)
• •Dependency injection: Pass dependencies as parameters rather than importing directly when it aids testing
• •Small, focused functions: Functions that do one thing are easier to test than multi-purpose functions
• •Co-locate tests: Place *.test.ts(x) files next to the code they test

Avoid Over-Engineering:

• •Only make changes directly requested or clearly necessary
• •Don't add features beyond what's asked
• •Don't add comments/docstrings to unchanged code
• •Minimum complexity for current task

Granular Commits: After each logical unit of work:

git add <files>
git commit -m "$(cat <<'EOF'
<type>(<scope>): <description>

<body explaining what and why>

Refs #<ISSUE_NUMBER>
EOF
)"

Commit types: feat, fix, docs, style, refactor, test, chore

Never add Co-Authored-By or any other attribution.

Step 7: Review for Modularity

Before moving on, review your implementation:

1. •Check for duplication: Did you copy similar code in multiple places? Extract to a shared utility
2. •Component size: Are any components >200 lines? Consider splitting into sub-components
3. •Utility candidates: Are there pure functions that could live in lib/ for reuse?
4. •Type definitions: Are complex inline types repeated? Extract to named types
5. •Test coverage: Can the core logic be unit tested independently?

If refactoring is needed, do it now before tests lock in the structure.

Step 8: Update Tests

• •Co-locate *.test.ts(x) files next to implementations
• •Mock external services at module boundaries
• •Run the project's test command after adding tests
• •Run coverage checks for substantial work (if available)
• •Test utilities separately: If you extracted shared functions, add unit tests for them

Step 9: Update Documentation

If behavior changed, update relevant docs:

• •/docs/*.md files (architecture, API, etc.)
• •CHANGELOG.md for user-facing features/fixes (write in plain language, skip internal changes)
• •Code comments where logic isn't self-evident
• •README if setup/usage changed
• •CLAUDE.md if guidelines need updates

Changelog Guidelines:

• •Only include user-facing changes (features users see, bugs they experienced)
• •Write in plain language (no "API", "SSR", "cache" jargon)
• •Use active voice: "Create shareable links" not "Shareable links were added"
• •Group by category (e.g., Features, Fixes, Performance)
• •Bold the feature name: Feature name - brief description

Step 10: Quality Gates

Before creating PR, run all project quality checks. Discover available scripts from CLAUDE.md or package.json and run them. Typical checks include:

• •Lint/format
• •Type checking
• •Tests
• •Coverage (for substantial changes)

Fix any issues and commit the fixes.

Step 10.5: Identify Manual Deployment Requirements

Review your changes and identify if ANY manual deployment steps are needed:

Check for these indicators:

• •New entries in .env.example or references to new env vars → Environment variable setup required
• •Changes to docker-compose*.yml → Docker configuration changes required
• •New external service integrations → API keys or service configuration required
• •Changes to routing, ports, or health checks → Load balancer/proxy updates may be required
• •Database schema changes that can't auto-migrate → Manual migration steps required
• •New dependencies on external services → Infrastructure provisioning may be required

Document all manual steps - you'll need these for the PR warning block in Step 12.

Step 11: Push Changes

git push -u origin <branch-name>

Step 12: Create Pull Request

PR titles MUST use conventional commit format:

<type>(<scope>): <description>

Types: feat, fix, docs, refactor, test, chore, perf Scope: The affected area (e.g., auth, templates, api, frontend)

IMPORTANT: Manual Deployment Steps Warning

If the implementation requires ANY manual steps for deployment, add a prominent warning at the TOP of the PR body. Manual steps include:

• •Adding or updating environment variables
• •Changes to load balancer or reverse proxy configuration
• •Docker Compose modifications
• •Database migrations that need manual intervention
• •Infrastructure changes (DNS, CDN, certificates)
• •Third-party service configuration (API keys, webhooks)
• •Feature flags that need to be enabled

gh pr create --title "<type>(<scope>): <description>" --body "$(cat <<'EOF'
<INCLUDE WARNING BLOCK IF MANUAL STEPS REQUIRED - SEE BELOW>

## Summary

Closes #<ISSUE_NUMBER>

<1-3 bullet points describing what was done>

## Changes

- <file/component>: <what changed>
- <file/component>: <what changed>

## Test Plan

- [ ] <how to test change 1>
- [ ] <how to test change 2>

## Checklist

- [ ] Code follows project guidelines (CLAUDE.md)
- [ ] Tests added/updated
- [ ] Documentation updated (if applicable)
- [ ] CHANGELOG.md updated for user-facing changes
- [ ] Lint/format checks pass
- [ ] Tests pass

🤖 Generated with [Claude Code](https://claude.ai/code)
EOF
)"

Warning Block Format (add at TOP of PR body when manual steps are required):

> [!WARNING]
> ## Manual Deployment Steps Required
>
> This PR requires the following manual actions before/after deployment:
>
> ### Environment Variables
> - [ ] Add `NEW_API_KEY` to production environment
> - [ ] Update `DATABASE_URL` connection string
>
> ### Infrastructure
> - [ ] Update load balancer health check path to `/api/health`
> - [ ] Add new DNS record for `api.example.com`
>
> ### Docker/Compose
> - [ ] Add new volume mount in `docker-compose.prod.yml`
>
> **Do not merge until these steps are planned and assigned.**

Only include sections that are relevant. The warning ensures reviewers and deployers are aware of required manual steps before merging.

Step 13: Summary

Provide implementation summary:

• •Branch name and PR link
• •List of commits made
• •Files changed
• •Tests added/modified
• •Documentation updated
• •Any follow-up items or known limitations

Important Guidelines

1. •Read CLAUDE.md first: Understand project-specific requirements
2. •Explore before coding: Use codebase-locator/analyzer agents to understand existing patterns
3. •Match existing style: Follow conventions already in the codebase
4. •Small commits: Each commit should be one logical change
5. •Test as you go: Don't leave testing for the end
6. •Ask when unsure: Better to clarify than to implement wrong
7. •Update todos: Keep TodoWrite in sync with progress
8. •Don't scope creep: Implement exactly what the issue asks, nothing more
9. •DRY principle: Extract duplicated code into shared utilities in lib/
10. •Keep it testable: Prefer pure functions; extract logic that can be unit tested independently

Sub-Issue Handling

If the issue is part of a parent/sub-issue hierarchy (using GitHub's built-in sub-issues feature):

1. •

   Check if this issue has a parent or sub-issues:

   bash

   # View issue details including parent/sub-issue relationships
   gh issue view <ISSUE_NUMBER>
   

2. •

   Treat each sub-issue as a separate task in TodoWrite

3. •

   Commit after completing each logical unit of work

4. •

   When a sub-issue is complete, close it to automatically update the parent's progress:

   bash

   gh issue close <SUB_ISSUE_NUMBER>
   

Note: GitHub's sub-issue feature automatically tracks progress on parent issues when sub-issues are closed. No need to manually update issue bodies.

Related Skills

Before: Use forge-create-issue to plan and create the issue. After implementing: Use forge-reflect-pr to self-review before requesting review. After review: Use forge-address-pr-feedback to address reviewer comments. After merging: Use forge-update-changelog to document user-facing changes. Full workflow: forge-setup-project → forge-create-issue → forge-implement-issue → forge-reflect-pr → forge-address-pr-feedback → forge-update-changelog

Example Usage

/forge-implement-issue 123
/forge-implement-issue https://github.com/owner/repo/issues/123