Read Issue Context

Retrieve all context from a GitHub issue before starting work.

When to Use

• Before starting implementation work
• When context is needed from prior work
• When checking if issue has been partially addressed
• When understanding design decisions made earlier
• When resuming work after a break

Quick Reference

# Get issue details
gh issue view <number>

# Get issue with all comments (implementation history)
gh issue view <number> --comments

# Get structured JSON for parsing
gh issue view <number> --json title,body,comments,labels,assignees,milestone,state

# Get specific field
gh issue view <number> --json body --jq '.body'

# Get linked PRs
gh pr list --search "issue:<number>"

# Get issue timeline
gh api repos/{owner}/{repo}/issues/<number>/timeline

Workflow

Starting Work on an Issue

1. Get issue details: gh issue view <number>
2. Read all comments: gh issue view <number> --comments
3. Check linked PRs: gh pr list --search "issue:<number>"
4. Note key context:
   • Design decisions from comments
   • Blockers or dependencies
   • Acceptance criteria
   • Related issues

Example Session

# 1. Read issue #123
gh issue view 123

# 2. Check for prior work
gh issue view 123 --comments

# 3. See if any PRs exist
gh pr list --search "issue:123"

# 4. Get machine-readable data if needed
gh issue view 123 --json title,body,labels,state

Data Extraction

Get Specific Fields

# Title only
gh issue view <number> --json title --jq '.title'

# Body content
gh issue view <number> --json body --jq '.body'

# Labels as list
gh issue view <number> --json labels --jq '.labels[].name'

# Comment bodies
gh issue view <number> --json comments --jq '.comments[].body'

# Comment count
gh issue view <number> --json comments --jq '.comments | length'

Parse Comments for Keywords

# Find design decisions
gh issue view <number> --json comments --jq '.comments[].body' | grep -i "design decision"

# Find blockers
gh issue view <number> --json comments --jq '.comments[].body' | grep -i "blocked\|blocker"

# Find completed items
gh issue view <number> --json comments --jq '.comments[].body' | grep -i "completed\|done"

Status Checking

Issue State

# Check if open or closed
gh issue view <number> --json state --jq '.state'

# Check closure reason
gh issue view <number> --json stateReason --jq '.stateReason'

# Check assignees
gh issue view <number> --json assignees --jq '.assignees[].login'

Related Items

# Find PRs that close this issue
gh pr list --search "closes:#<number>"

# Find mentions in other issues
gh issue list --search "in:body #<number>"

# Find commits referencing issue
gh api search/commits?q=repo:{owner}/{repo}+<number>

Error Handling

| Problem | Solution | |---------|----------| | Issue not found | Check issue number, may be in different repo | | No comments | Issue may be new or have minimal discussion | | Auth error | Run gh auth status to verify | | Rate limited | Wait or use authenticated requests |

Best Practices

1. Always read comments first - They contain implementation history
2. Check for linked PRs - Prior attempts may exist
3. Note acceptance criteria - Success criteria should be clear
4. Look for blockers - Dependencies may not be resolved
5. Extract key decisions - Design choices should inform implementation

References

• See .claude/shared/github-issue-workflow.md for complete workflow
• See CLAUDE.md for project conventions