complete-github-issue

name: complete-github-issue description: Use when asked to work on, implement, or complete a GitHub issue — before writing any code, checks issue state, existing PRs, git history, and codebase to determine what work remains or if the issue is already resolved argument-hint: "[issue-number]"

Complete GitHub Issue

Overview

Systematically assess a GitHub issue's completion state before implementing anything. Check the issue, git history, PRs, and codebase to determine: fully done, partially done, or not started. Then act accordingly.

Core principle: Reconnaissance before implementation. Never implement what's already done.

When to Use

• Asked to "implement issue #N" or "complete issue #N"
• Given a GitHub issue URL or number to work on
• Asked to "close" or "resolve" an issue
• Working through a backlog of issues

When NOT to use:

• Creating a new issue (not implementing one)
• Reviewing a PR (separate workflow)
• Issue is purely a discussion/question (no implementation needed)

The Process

digraph complete_issue {
    rankdir=TB;

    "Read issue contents via gh" [shape=box];
    "Issue has implementation work?" [shape=diamond];
    "No code needed — respond/comment" [shape=box style=filled fillcolor=lightyellow];
    "Check for linked PRs and branches" [shape=box];
    "Check git log for related commits" [shape=box];
    "Check codebase against acceptance criteria" [shape=box];
    "Fully implemented?" [shape=diamond];
    "Partially implemented?" [shape=diamond];
    "Find implementing commit(s)" [shape=box];
    "Close issue with commit reference" [shape=box style=filled fillcolor=lightgreen];
    "List remaining criteria only" [shape=box];
    "Implement remaining work" [shape=box style=filled fillcolor=lightblue];
    "Implement all acceptance criteria" [shape=box style=filled fillcolor=lightblue];
    "Verify/create test coverage" [shape=box style=filled fillcolor=lightyellow];

    "Read issue contents via gh" -> "Issue has implementation work?";
    "Issue has implementation work?" -> "No code needed — respond/comment" [label="no"];
    "Issue has implementation work?" -> "Check for linked PRs and branches" [label="yes"];
    "Check for linked PRs and branches" -> "Check git log for related commits";
    "Check git log for related commits" -> "Check codebase against acceptance criteria";
    "Check codebase against acceptance criteria" -> "Fully implemented?";
    "Fully implemented?" -> "Find implementing commit(s)" [label="yes"];
    "Find implementing commit(s)" -> "Close issue with commit reference";
    "Fully implemented?" -> "Partially implemented?" [label="no"];
    "Partially implemented?" -> "List remaining criteria only" [label="yes"];
    "List remaining criteria only" -> "Implement remaining work";
    "Partially implemented?" -> "Implement all acceptance criteria" [label="no"];
    "Implement remaining work" -> "Verify/create test coverage";
    "Implement all acceptance criteria" -> "Verify/create test coverage";
}

Step 1: Read the Issue

gh issue view <NUMBER>

Extract from the issue:

• Acceptance criteria (checkboxes, requirements, deliverables)
• Referenced files (paths, components, endpoints mentioned)
• Labels and state (open/closed, assigned, linked PRs)

If the issue lacks clear acceptance criteria, derive them from the description. List them explicitly before proceeding.

Step 2: Reconnaissance (BEFORE Any Implementation)

Run these checks — all are required before writing any code:

2a. Check for linked PRs

# Search for PRs that reference this issue
gh pr list --state all --search "<ISSUE_NUMBER>" --limit 10

# Check if any PR body references the issue
gh pr list --state all --search "closes #<NUMBER> OR fixes #<NUMBER> OR resolves #<NUMBER>"

If a merged PR exists that addresses the issue, skip to Step 3 (assess completion).

2b. Check git history

# Search commit messages for issue references
git log --all --oneline --grep="#<NUMBER>"

# Search commits touching files mentioned in the issue
git log --all --oneline -- <referenced-files>

# Check for feature branches
git branch -a | grep -i "<keyword>"

2c. Check codebase against each acceptance criterion

For EACH acceptance criterion, verify whether the code already satisfies it:

# Search for implementations of specific features mentioned
# Use Grep/Glob to check if components/endpoints/logic exist

Be specific. Don't just check if a file exists — verify the actual behavior matches the criterion.

Step 3: Assess Completion State

Score each acceptance criterion:

## Completion Assessment

- [x] Criterion 1 — DONE (evidence: <file>:<line>, commit <sha>)
- [ ] Criterion 2 — NOT DONE (missing: <what's missing>)
- [x] Criterion 3 — DONE (evidence: <file>:<line>)

Present this assessment to the user before proceeding.

Decision:

Step 4a: Close with Commit Reference (Fully Done)

Find the implementing commit(s):

# Find the most relevant commit(s)
git log --all --oneline -- <files-that-changed>

# Get the full commit hash for the primary implementing commit
git log --all --format="%H %s" -- <primary-file> | head -5

Then close the issue:

gh issue close <NUMBER> --comment "Implemented in <commit-sha>.

Acceptance criteria verified:
- [x] Criterion 1 (<file>:<line>)
- [x] Criterion 2 (<file>:<line>)
..."

Before closing, run Step 5 (Test Verification) to confirm tests exist and pass for the implemented criteria. If tests are missing, create them before closing — an issue isn't truly "done" without test coverage. This applies even when you didn't write the implementation.

Always include: the commit SHA, which criteria are satisfied, and where the evidence is.

Step 4b: Implement Remaining (Partially Done)

1. List ONLY the unmet criteria — do not re-implement done work
2. Implement each remaining criterion
3. After implementation, proceed to Step 5 (Test Verification)

Step 4c: Implement All (Not Started)

1. Follow normal implementation workflow
2. After implementation, proceed to Step 5 (Test Verification)

Step 5: Test Verification (Required After Any Implementation)

After implementing code in Step 4b or 4c, tests MUST be checked and updated.

5a. Check existing test coverage

# Find tests related to changed files
# For each file you modified (e.g., MyComponent.tsx), check:
Glob("**/<ComponentName>*.test.*")
Glob("**/<module-name>*.test.*")

# Search for test files that import the changed modules
Grep(pattern: "import.*<changed-module>", glob: "*.test.*")

5b. Update or create tests

What to test:

• Each acceptance criterion should have at least one test asserting it
• Edge cases mentioned in the issue
• Regression: existing behavior that should NOT have changed

5c. Run the full test suite

# Run unit tests
npm run jest

# Run typecheck
npm run typecheck

# Run E2E tests if UI behavior changed
npm run test:e2e

All tests must pass before claiming completion. Show output with pass/fail counts.

Quick Reference

Common Mistakes

Jumping straight to implementation

• You read the issue and start coding without checking if work already exists
• Fix: ALWAYS complete Step 2 reconnaissance before any implementation

Ignoring closed-but-open state mismatch

• Issue is closed but you implement anyway, or issue is open but work is already done
• Fix: Issue state is informational, not authoritative. Check the CODE, not just the label.

Shallow codebase checks

• Checking if a file exists is not the same as verifying acceptance criteria are met
• Fix: For each criterion, verify the actual behavior, not just file existence

Re-implementing done work

• Some criteria are met but you implement everything from scratch
• Fix: Score EACH criterion individually. Only implement what's missing.

Closing without evidence

• "This looks done" without specific commit references or file locations
• Fix: Always cite commit SHAs and file:line evidence in close comments

Skipping test verification

• Implementing code without checking for existing tests, updating broken tests, or creating missing tests
• Fix: Step 5 is mandatory. Every acceptance criterion needs test coverage.

Red Flags — STOP

If you catch yourself doing any of these, go back to Step 2:

• Writing code before checking git history
• "I'll just implement it fresh, it's faster"
• Assuming nothing exists because the issue is open
• Assuming everything exists because the issue is closed
• Skipping the completion assessment table
• Implementing without updating or creating tests
• Closing an issue when tests for the implemented criteria don't exist