/issue-close

Issue Close

You are an Issue Management Specialist responsible for properly closing issues with comprehensive completion summaries and verification.

Your Task

Close an issue with a complete summary including:

1. Work completed
2. Artifacts delivered
3. Verification checklist
4. Related commits and PRs
5. Next steps or follow-up items

Input Modes

Basic Close

/issue-close 17

Closes issue #17 with auto-generated summary.

Close with Reason

/issue-close 17 --reason "Implemented in commit abc123, all tests passing"

Closes with custom reason/summary.

Close Without Verification

/issue-close 17 --no-verify

Skips verification checks (use with caution).

Close and Link Artifacts

/issue-close 17 --link-artifacts

Automatically finds and links related AIWG artifacts.

Workflow

Step 1: Validate Issue

Check Issue Exists and is Open:

# GitHub
gh issue view {issue_number}

# Gitea (use MCP)
# Query issue via mcp__gitea__ tools

Validation Checks:

• Issue exists
• Issue is currently open
• User has permission to close
• No blocking dependencies (check for "Blocked by" labels or comments)

If validation fails:

Error: Cannot close issue #{number}
Reason: {validation_failure_reason}

Suggestions:
- Verify issue number is correct
- Check that issue is not already closed
- Ensure you have permission to close issues
- Resolve blocking dependencies first

Step 2: Gather Issue Context

Collect Issue Details:

• Issue title
• Issue body/description
• Labels
• Assignees
• Milestone
• Created date
• Comments (extract important info)

Extract Acceptance Criteria:

Parse issue body for checklist items:

### Acceptance Criteria
- [x] Feature implemented
- [x] Tests added
- [ ] Documentation updated  ← INCOMPLETE

If acceptance criteria incomplete:

Warning: Not all acceptance criteria are checked.

Incomplete items:
- [ ] Documentation updated

Proceed with closing? (--no-verify to skip this check)

Step 3: Find Related Work

Scan Recent Commits:

# Search commit messages for issue reference
git log --all --grep="#{issue_number}" --oneline

# Also check variations
git log --all --grep="issue.*#{issue_number}" --oneline
git log --all --grep="[#]#{issue_number}" --oneline

Scan AIWG Artifacts:

# Use grep to find references
grep -r "#{issue_number}" .aiwg/
grep -r "@issues/{issue_number}" .aiwg/

Scan Code References:

# Find TODOs and issue references in code
grep -r "TODO.*#{issue_number}" src/
grep -r "@issue #{issue_number}" src/
grep -r "Issue #{issue_number}" src/

Find Related PRs:

# GitHub
gh pr list --search "#{issue_number}" --state all

# Gitea (use MCP to search)

Step 4: Verify Completion

Verification Checklist (unless --no-verify):

## Pre-Close Verification

### Code Changes
- [ ] Commits found referencing this issue
- [ ] Code review completed (check PR status)
- [ ] No open PRs still referencing this issue

### Testing
- [ ] Tests added for new functionality
- [ ] All tests passing (check CI status)
- [ ] No test failures in recent runs

### Documentation
- [ ] Code documentation updated
- [ ] User documentation updated (if user-facing)
- [ ] AIWG artifacts updated (requirements, architecture, etc.)

### Quality
- [ ] No new lint errors introduced
- [ ] Code coverage maintained or improved
- [ ] No security vulnerabilities introduced

### Acceptance Criteria
- [ ] All acceptance criteria met (from issue template)
- [ ] Definition of Done satisfied

### Cleanup
- [ ] No TODOs left in code referencing this issue
- [ ] No FIXME comments unresolved
- [ ] Feature flags removed (if temporary)

Auto-Check Where Possible:

# Check CI status of recent commits
gh run list --limit 5 --json conclusion

# Check for remaining TODOs
grep -r "TODO.*#${issue_number}" src/ test/

# Check test coverage (if available)
npm test -- --coverage

Report Verification Results:

## Verification Results

✅ Code changes: 3 commits found
✅ Code review: PR #45 merged
✅ Tests: All passing (15/15)
⚠️  Documentation: AIWG artifacts not updated
❌ TODOs: 2 TODO comments still reference this issue

Blockers:
- Resolve remaining TODOs before closing
- Update .aiwg/requirements/use-cases/UC-017.md

Proceed anyway? Use --no-verify to skip checks.

Step 5: Generate Completion Summary

Using task-completed.md template, generate comprehensive summary:

## Task Completed

**Status**: Completed
**Closed by**: {user}
**Completion date**: {timestamp}
**Time to resolution**: {days} days

## Original Request

{issue_title}

{issue_body_summary}

## Summary of Work

{auto_generated_summary_from_commits_and_artifacts}

## Deliverables

### Code Changes
- Commits: {count}
  - {sha1}: {message}
  - {sha2}: {message}
- Pull Requests: {count}
  - PR #{number}: {title} (Merged: {date})

### Artifacts Created/Updated
- `{artifact_path}` - {description}
- `{artifact_path}` - {description}

### Tests Added
- `{test_path}` - {description}
- Coverage: {percentage}% ({lines} lines covered)

### Documentation Updated
- `{doc_path}` - {description}

## Implementation Details

### Files Modified
- `{file_path}` - {change_summary}
- `{file_path}` - {change_summary}

Total changes: +{lines_added} -{lines_removed} across {files_count} files

### Key Decisions

{if_any_ADRs_or_design_decisions}
- {decision_1}: {rationale}
- {decision_2}: {rationale}

## Verification

- [x] All acceptance criteria met
- [x] Tests passing ({test_count} tests)
- [x] Code reviewed and approved
- [x] Documentation updated
- [x] CI/CD pipeline passing
- [x] No outstanding TODOs
- [x] Ready for deployment

## Related Items

- Closes: #{issue_number}
- Related PRs: #{pr_numbers}
- Related issues: #{related_issue_numbers}
- Artifacts: {artifact_paths}
- Commits: {commit_range}

## Impact Assessment

### User Impact
- {impact_description}

### System Impact
- Performance: {performance_changes}
- Security: {security_improvements}
- Dependencies: {dependency_updates}

## Deployment Notes

{if_applicable}
- Deployment required: {yes/no}
- Migration needed: {yes/no}
- Feature flags: {enabled/disabled}
- Rollback plan: {description}

## Follow-Up Items

{if_applicable}
### Future Enhancements
- {enhancement_1} - Consider for future milestone
- {enhancement_2} - Tracked in #{issue_number}

### Technical Debt
- {debt_item_1} - Address in #{issue_number}

### Monitoring
- Watch for: {metrics_to_monitor}
- Alert thresholds: {thresholds}

## Next Steps

1. {next_step_1}
2. {next_step_2}
3. {next_step_3}

---

*This issue has been completed and verified. All acceptance criteria met and tests passing. Closing as complete.*

Step 6: Close Issue with Summary

GitHub:

# Close issue with comment
gh issue close {issue_number} --comment "{completion_summary}"

# Add labels if applicable
gh issue edit {issue_number} --add-label "completed"

Gitea:

# Add completion comment first
mcp__gitea__create_issue_comment \
  --owner {owner} \
  --repo {repo} \
  --issue_number {number} \
  --body "{completion_summary}"

# Then close issue
mcp__gitea__edit_issue \
  --owner {owner} \
  --repo {repo} \
  --issue_number {number} \
  --state closed

Step 7: Update Related Issues

If this issue unblocks others:

# Find issues blocked by this one
gh issue list --search "blocked by #{issue_number}"

# Add unblocking comment to each
for blocked_issue in ${blocked_issues}; do
  gh issue comment ${blocked_issue} --body "✅ Unblocked: Issue #{issue_number} has been resolved."
done

If this closes a milestone:

# Check milestone status
gh issue list --milestone "{milestone}" --state open

# If all issues closed
gh api repos/{owner}/{repo}/milestones/{milestone_id} \
  -X PATCH \
  -f state=closed \
  -f description="Completed {date}: All issues resolved"

Step 8: Generate Closure Report

## Issue Closure Report

**Issue**: #{issue_number} - {title}
**Closed by**: {user}
**Closed at**: {timestamp}
**Resolution time**: {duration}

### Summary

{brief_summary}

### Work Completed

- Commits: {count}
- PRs merged: {count}
- Files changed: {count}
- Tests added: {count}
- Artifacts updated: {count}

### Verification

All pre-close checks passed:
- ✅ Acceptance criteria met
- ✅ Tests passing
- ✅ Code reviewed
- ✅ Documentation updated
- ✅ CI/CD passing

### Related Updates

{if_applicable}
- Unblocked issues: #{numbers}
- Milestone completed: {milestone_name}
- Follow-up issues created: #{numbers}

### Links

- Issue: {issue_url}
- PR: {pr_url}
- Commits: {commit_range_url}
- Artifacts: {artifact_paths}

---

Issue #{issue_number} successfully closed with verification complete.

Advanced Features

Automatic Follow-Up Issue Creation

If incomplete items detected:

## Follow-Up Items Detected

Creating follow-up issues for:

1. Documentation improvements
   - Created issue #{new_number}: "Update API documentation for feature X"

2. Technical debt
   - Created issue #{new_number}: "Refactor auth logic for better testability"

3. Future enhancements
   - Created issue #{new_number}: "Add support for OAuth providers"

These items were moved to new issues to allow closing #{original_issue}.

Milestone Auto-Complete

If this is the last issue in a milestone:

## Milestone Completed! 🎉

Issue #{issue_number} was the last open issue in milestone "{milestone}".

Milestone summary:
- Total issues: {count}
- Completed: {count}
- Duration: {start_date} - {end_date}
- Success rate: 100%

The milestone has been automatically marked as complete.

Artifact Traceability Update

Update AIWG artifacts with completion status:

## References

- Implements: @.aiwg/requirements/UC-017.md ✅ Completed
- Related issue: #17 (Closed: {date})
- Implementation: @src/issue-sync.ts
- Tests: @test/unit/issue-sync.test.ts

Changelog Generation

Add entry to CHANGELOG.md:

### Issue #17 - Issue sync automation (Closed: 2025-01-13)

- Implemented automatic issue synchronization from commits
- Added issue comment templates
- Created /issue-sync, /issue-close, /issue-comment commands
- Test coverage: 85%
- PRs: #45, #46

Closes #17

Configuration

.aiwg/config.yaml

issue_close:
  verify_before_close: true
  require_all_acceptance_criteria: true
  auto_link_artifacts: true
  create_follow_ups: true
  update_changelog: true
  minimum_time_open: 1h  # Prevent immediate close
  labels:
    on_close: ["completed", "verified"]
    on_skip_verify: ["closed-unverified"]

Error Handling

Issue Already Closed

Error: Issue #{number} is already closed.

Status: Closed {date} by {user}
Resolution: {previous_summary}

No action needed.

Incomplete Verification

Error: Pre-close verification failed.

Failed checks:
- ❌ Tests: 2 tests failing
- ❌ TODOs: 3 TODO comments unresolved
- ⚠️  Documentation: No AIWG artifacts updated

Options:
1. Fix failing checks and try again
2. Use --no-verify to skip checks (not recommended)
3. Document why checks can be skipped

Permission Denied

Error: Cannot close issue #{number} - insufficient permissions.

Required permission: triage or maintain role

Suggestions:
- Request permission from repository maintainer
- Have maintainer close the issue
- Use GitHub/Gitea UI to close manually

Best Practices

When to Close

Close immediately when:

• All acceptance criteria met
• Tests passing
• Code reviewed and merged
• Documentation complete

Delay closing when:

• Awaiting deployment verification
• Monitoring for issues in production
• Need user acceptance testing
• Dependent work not complete

Creating Follow-Ups

Good follow-up issues:

Title: Improve error handling in issue sync (follow-up to #17)

Description:
While implementing #17, we identified opportunities to improve error handling:
- Add retry logic for API failures
- Better error messages for invalid issue references
- Graceful degradation when API unavailable

This is a follow-up enhancement, not blocking #17 completion.

Labels: enhancement, technical-debt

Closure Comments

Comprehensive:

✅ All acceptance criteria met
✅ 15 tests added, all passing
✅ Code reviewed and approved in PR #45
✅ Documentation updated in .aiwg/requirements/

Ready for deployment to production.

Concise:

Implemented in commit abc123. Tests passing. Docs updated. Ready to deploy.

References

• Template: @agentic/code/frameworks/sdlc-complete/templates/issue-comments/task-completed.md
• Related: @agentic/code/frameworks/sdlc-complete/commands/issue-sync.md, @agentic/code/frameworks/sdlc-complete/commands/issue-comment.md
• MCP tools: Gitea issue management
• GitHub CLI: gh issue close

Success Criteria

This command succeeds when:

• Issue is successfully closed
• Comprehensive completion summary added
• All verification checks passed (unless --no-verify)
• Related issues updated (if blocking others)
• Artifacts linked and updated
• Follow-up issues created (if needed)
• Changelog updated (if configured)
• Clear closure report generated