gh-bodangren-git-workflow-skills/issue-executor/references/work-on-issue.md

Work on Issue Workflow

Select and start work on a specific issue from assigned GitHub issues.

Purpose

Load full context for an issue and create a feature branch to begin implementation. Ensures clean workflow start with all necessary context loaded before any code is written.

When to Use

Use this workflow when:

• Starting work on a new issue
• Switching between issues
• After completing previous issue
• Beginning work session

Workflow

1. Verify Clean Working State

# Check current branch is clean
CURRENT_BRANCH=$(git branch --show-current)
if [ "$CURRENT_BRANCH" != "main" ]; then
  echo "⚠ Currently on branch: $CURRENT_BRANCH"
  echo "Finish current work or switch to main first."
  exit 1
fi

# Check for uncommitted changes
if [ -n "$(git status --porcelain)" ]; then
  echo "⚠ Uncommitted changes detected"
  git status
  echo "Commit or stash changes before starting new issue."
  exit 1
fi

2. Get Current User's Assigned Issues

# Get all open issues assigned to current user
gh issue list \
  --assignee @me \
  --state open \
  --json number,title,labels,milestone,createdAt \
  --limit 50 | jq '.'

3. Get Milestone Details for Context

# Get current sprint milestones
gh api repos/:owner/:repo/milestones \
  --jq '.[] | select(.state == "open") | {number, title, state, dueOn}' \
  | jq -s 'sort_by(.dueOn)'

4. Check for Spec Conflicts

For each candidate issue, verify no conflicting work in progress:

# Extract affected specs from issue body
ISSUE_NUM=123
AFFECTED_SPECS=$(gh issue view $ISSUE_NUM --json body --jq .body \
  | rg "Affected Specs.*" -A 5 \
  | rg "docs/specs/([^/]+)" -o -r '$1')

# Check if any other open issues affect same specs
for SPEC in $AFFECTED_SPECS; do
  CONFLICTS=$(gh issue list \
    --assignee @me \
    --state open \
    --search "docs/specs/$SPEC in:body" \
    --json number,title)

  if [ $(echo "$CONFLICTS" | jq 'length') -gt 1 ]; then
    echo "⚠ Conflict detected: Multiple issues affect $SPEC"
    echo "$CONFLICTS" | jq -r '.[] | "#\(.number) - \(.title)"'
  fi
done

5. Analyze and Recommend Issues

Sort and prioritize issues by:

1. Priority: P0 > P1 > P2 > P3
2. Sprint alignment: Current milestone first
3. Spec readiness: Issues with existing specs
4. Dependencies: Non-blocked issues first

# Parse priorities from labels
P0_ISSUES=$(gh issue list --assignee @me --state open --label "priority:P0" --json number,title,milestone)
P1_ISSUES=$(gh issue list --assignee @me --state open --label "priority:P1" --json number,title,milestone)
P2_ISSUES=$(gh issue list --assignee @me --state open --label "priority:P2" --json number,title,milestone)

# Show recommendations
echo "=== Recommended Issues ==="
echo ""
echo "Priority P0 (Critical):"
echo "$P0_ISSUES" | jq -r '.[] | "  #\(.number) - \(.title) [\(.milestone.title)]"'
echo ""
echo "Priority P1 (High):"
echo "$P1_ISSUES" | jq -r '.[] | "  #\(.number) - \(.title) [\(.milestone.title)]"'
echo ""
echo "Priority P2 (Medium):"
echo "$P2_ISSUES" | jq -r '.[] | "  #\(.number) - \(.title) [\(.milestone.title)]"'

Present top 3-5 recommendations:

Top recommendations:

1. #201 - Curriculum Framework (P1, S2) ✓ Specs ready
2. #202 - Lesson Player (P1, S2) ✓ Specs ready
3. #203 - Virtual Laboratory System (P2, S2) ⚠ Depends on #201

Which issue would you like to start? (Enter number)

6. Read Full Issue Details

After user selects issue:

ISSUE_NUMBER=201

# Read complete issue
gh issue view $ISSUE_NUMBER

# Read ALL comments (including review suggestions)
gh issue view $ISSUE_NUMBER --comments

IMPORTANT: Pay special attention to review comments posted by review-sprint. These may include:

• Architecture compliance suggestions
• Wording and clarity improvements
• Planning enhancements
• Spec change recommendations

Consider these suggestions during implementation but use your judgment on how to apply them.

7. Extract and Validate Spec References

# Get issue body
ISSUE_BODY=$(gh issue view $ISSUE_NUMBER --json body --jq .body)

# Extract affected specs
AFFECTED_SPECS=$(echo "$ISSUE_BODY" | rg "Affected Specs" -A 10 | rg "docs/specs/[^)]+")

# Verify each spec exists
echo "Validating spec references..."
for SPEC_PATH in $AFFECTED_SPECS; do
  if [ -f "$SPEC_PATH" ]; then
    echo "✓ Found: $SPEC_PATH"
  else
    echo "✗ Missing: $SPEC_PATH"
    echo ""
    echo "⚠ Spec not found. Run 'init-spec' to create it first."
    exit 1
  fi
done

8. Check Related Issues and Dependencies

# Look for "Related Issues" section in issue body
RELATED_ISSUES=$(echo "$ISSUE_BODY" | rg "Related Issues" -A 5 | rg "#[0-9]+" -o)

if [ -n "$RELATED_ISSUES" ]; then
  echo "=== Related Issues ==="
  for RELATED in $RELATED_ISSUES; do
    RELATED_NUM=$(echo "$RELATED" | tr -d '#')
    RELATED_STATE=$(gh issue view $RELATED_NUM --json state --jq .state)
    RELATED_TITLE=$(gh issue view $RELATED_NUM --json title --jq .title)

    if [ "$RELATED_STATE" = "OPEN" ]; then
      echo "⚠ $RELATED - $RELATED_TITLE (OPEN - may be dependency)"
    else
      echo "✓ $RELATED - $RELATED_TITLE (CLOSED)"
    fi
  done
fi

# Check for blocking issues
BLOCKING=$(echo "$ISSUE_BODY" | rg -i "blocked by|depends on" -A 2)
if [ -n "$BLOCKING" ]; then
  echo ""
  echo "⚠ Warning: This issue may have dependencies:"
  echo "$BLOCKING"
  echo ""
  read -p "Continue anyway? (y/n) " -n 1 -r
  echo
  if [[ ! $REPLY =~ ^[Yy]$ ]]; then
    echo "Aborted. Select a different issue."
    exit 1
  fi
fi

9. Read Affected Specs

echo "=== Reading Affected Specs ==="
for SPEC_PATH in $AFFECTED_SPECS; do
  echo ""
  echo "--- $SPEC_PATH ---"
  cat "$SPEC_PATH"
  echo ""
done

# If spec has design.md, read it too
for SPEC_PATH in $AFFECTED_SPECS; do
  SPEC_DIR=$(dirname "$SPEC_PATH")
  DESIGN_PATH="$SPEC_DIR/design.md"

  if [ -f "$DESIGN_PATH" ]; then
    echo "--- $DESIGN_PATH ---"
    cat "$DESIGN_PATH"
    echo ""
  fi
done

10. Read Development Retrospective

Read accumulated learnings to inform implementation:

if [ -f "RETROSPECTIVE.md" ]; then
  echo ""
  echo "=== Development Retrospective ==="
  cat RETROSPECTIVE.md
  echo ""
  echo "Consider these learnings during implementation:"
  echo "  - Apply success patterns from recent issues"
  echo "  - Avoid known friction points"
  echo "  - Reference well-specified capabilities"
  echo "  - Follow active improvement initiatives"
  echo ""
elif [ -f "docs/RETROSPECTIVE.md" ]; then
  echo ""
  echo "=== Development Retrospective ==="
  cat docs/RETROSPECTIVE.md
  echo ""
  echo "Consider these learnings during implementation."
  echo ""
else
  echo ""
  echo "ℹ No RETROSPECTIVE.md found (this is normal for first few issues)"
  echo ""
fi

Purpose: The retrospective captures:

• Recent patterns: What worked/didn't work in last 3-5 issues
• Historical wisdom: Compressed learnings from earlier issues
• Spec quality: Which specs are good references vs need improvement
• Active improvements: Current process improvements being tracked

This context helps avoid repeating past mistakes and apply proven patterns.

11. Create Feature Branch

# Extract title and create kebab-case branch name
TITLE=$(gh issue view $ISSUE_NUMBER --json title --jq .title)
KEBAB_TITLE=$(echo "$TITLE" | tr '[:upper:]' '[:lower:]' | sed -E 's/[^a-z0-9]+/-/g;s/^-|-$//g' | cut -c1-40)

# Determine branch prefix from change type
CHANGE_TYPE=$(echo "$ISSUE_BODY" | rg "\[x\] (ADDED|MODIFIED|REMOVED)" -o -r '$1')

case "$CHANGE_TYPE" in
  "ADDED")
    PREFIX="feat"
    ;;
  "MODIFIED")
    PREFIX="feat"  # or "refactor" depending on scope
    ;;
  "REMOVED")
    PREFIX="refactor"
    ;;
  *)
    # Infer from labels
    if echo "$ISSUE_BODY" | rg -q "type:bug"; then
      PREFIX="fix"
    elif echo "$ISSUE_BODY" | rg -q "type:chore"; then
      PREFIX="chore"
    else
      PREFIX="feat"
    fi
    ;;
esac

BRANCH_NAME="${PREFIX}/${ISSUE_NUMBER}-${KEBAB_TITLE}"

# Create and switch to branch
git switch -c "$BRANCH_NAME"

echo "✓ Created and switched to: $BRANCH_NAME"

12. Initial Setup

Check if any setup is needed:

# Check if package.json changed recently (might need npm install)
MAIN_PACKAGE_DATE=$(git log -1 --format="%ai" main -- package.json 2>/dev/null)
if [ -n "$MAIN_PACKAGE_DATE" ]; then
  echo "Note: package.json was updated recently ($MAIN_PACKAGE_DATE)"
  echo "Running npm install..."
  npm install
fi

# Check if Prisma schema exists (might need generate)
if [ -f "prisma/schema.prisma" ]; then
  echo "Note: Prisma schema detected"
  echo "Running npx prisma generate..."
  npx prisma generate
fi

# Check for other setup scripts
if [ -f "scripts/setup.sh" ]; then
  echo "Note: Found setup script"
  echo "Running scripts/setup.sh..."
  bash scripts/setup.sh
fi

13. Update TODO.md

Add issue to "In Progress" section:

## In Progress

- [ ] #201 - Curriculum Framework (feat/201-curriculum-framework)
  - **Started**: 2025-10-21
  - **Branch**: feat/201-curriculum-framework
  - **Specs**: docs/specs/curriculum-management/spec.md
  - **Priority**: P1
  - **Milestone**: S2

If TODO.md doesn't have "In Progress" section, create it:

# Check if section exists
if ! grep -q "## In Progress" TODO.md; then
  # Add section after sprint section
  sed -i '/^## Phase/a \\n## In Progress\n' TODO.md
fi

# Add issue entry
cat >> TODO.md << EOF

- [ ] #${ISSUE_NUMBER} - ${TITLE} (${BRANCH_NAME})
  - **Started**: $(date +%Y-%m-%d)
  - **Branch**: ${BRANCH_NAME}
  - **Specs**: ${AFFECTED_SPECS}
  - **Priority**: ${PRIORITY}
  - **Milestone**: ${MILESTONE}
EOF

14. Update Sprint File

Find the relevant sprint file and update story status:

# Find sprint file (match milestone to sprint file)
MILESTONE=$(gh issue view $ISSUE_NUMBER --json milestone --jq .milestone.title)
SPRINT_NUM=$(echo "$MILESTONE" | rg "S([0-9]+)" -o -r '$1')
SPRINT_FILE="docs/sprint/S${SPRINT_NUM}.md"

if [ -f "$SPRINT_FILE" ]; then
  # Find the story section and update status
  # This is complex; in practice, manually update the file
  echo "Update $SPRINT_FILE:"
  echo "  - Find story section for: $TITLE"
  echo "  - Add: **Status**: In Progress"
  echo "  - Add: **Branch**: $BRANCH_NAME"
  echo "  - Add: **Started**: $(date +%Y-%m-%d)"
fi

Example sprint file update:

## Curriculum Framework

**User Story**: As an educator...

**Status**: In Progress
**Branch**: feat/201-curriculum-framework
**Started**: 2025-10-21
**Issue**: #201

15. Provide Summary

✓ Started work on issue #201

Issue: Curriculum Framework
Branch: feat/201-curriculum-framework
Priority: P1
Milestone: S2

Affected specs:
  - docs/specs/curriculum-management/spec.md

Review comments: 1 comment (review suggestions available)

Next steps:
  1. Review issue comments and review suggestions
  2. Review spec requirements and scenarios
  3. Implement according to acceptance criteria (considering review feedback)
  4. Write tests per test plan
  5. Run 'test-issue' before submitting
  6. Run 'submit-issue' when ready for PR

Dependencies to watch:
  - None identified

Happy coding! 🚀

Priority Order

Issues are recommended in this order:

1. P0 - Critical: Blocking bugs, production issues
2. P1 - High: Important features, high-value work
3. P2 - Medium: Standard features, improvements
4. P3 - Low: Nice-to-have, technical debt

Within same priority:

• Current sprint milestone before future sprints
• Issues with ready specs before those needing spec work
• Non-blocked issues before those with dependencies

Dependency Checking

Types of Dependencies

1. Hard dependencies: "Blocked by #123", "Depends on #123"

   • Must be completed first
   • Halt if not complete

2. Soft dependencies: "Related to #123", "See also #123"

   • Provide context but not blocking
   • Read for additional information

3. Spec dependencies: One spec depends on another

   • Check if dependency specs exist
   • Verify dependency requirements are clear

Handling Blocked Issues

If selected issue is blocked:

⚠ Issue #203 is blocked by #201 (Curriculum Framework)

#201 status: In Progress (50% complete)

Options:
1. Wait for #201 to complete
2. Select different issue
3. Proceed with risk (may need rework)

Recommendation: Select different issue and return to #203 later.

Spec Readiness Validation

Before starting work, ensure:

• All referenced specs exist in docs/specs/
• Specs have clear requirements
• Each requirement has scenarios
• Dependencies between specs are documented
• Design docs exist for complex changes

If spec is incomplete:

1. Consider running init-spec to complete it
2. Or flag issue for spec refinement before starting

File Update Patterns

TODO.md Format

## In Progress

- [ ] #201 - Curriculum Framework (feat/201-curriculum-framework)
  - **Started**: 2025-10-21
  - **Branch**: feat/201-curriculum-framework
  - **Specs**: docs/specs/curriculum-management/spec.md
  - **Priority**: P1
  - **Milestone**: S2
  - **Dependencies**: None

Sprint File Format

## Curriculum Framework

**User Story**: As an educator, I want to define course structures...

**Acceptance Criteria**:
- Course hierarchy supported
- Learning objectives trackable

**Status**: In Progress
**Branch**: feat/201-curriculum-framework
**Started**: 2025-10-21
**Issue**: #201
**Assigned**: @username

Error Handling

Dirty Working Directory

⚠ Error: Uncommitted changes detected

Please commit or stash changes before starting new issue:
  git add .
  git commit -m "wip: save progress"
  # or
  git stash

Then run 'next-issue' again.

Not on Main Branch

⚠ Error: Currently on branch: feat/123-old-issue

Please finish current work first:
  1. Complete implementation
  2. Run 'submit-issue' to create PR
  3. Or: git switch main (to abandon work)

Then run 'next-issue' again.

Missing Specs

⚠ Error: Spec not found
  docs/specs/curriculum-management/spec.md

Issue #201 references specs that don't exist yet.

Action required:
  1. Run: init-spec curriculum-management
  2. Create spec.md with requirements
  3. Run 'next-issue' again

No Available Issues

ℹ No issues assigned to you.

Possible actions:
  1. Check sprint backlog in GitHub
  2. Assign yourself an issue from current sprint
  3. Run 'seed-sprint' to create new issues
  4. Contact Scrum Master for assignment

Advanced: Context Caching

To optimize repeated API calls, consider caching:

# Cache issue list for 5 minutes
CACHE_FILE="/tmp/gh-issues-cache-$(date +%Y%m%d-%H%M).json"
if [ ! -f "$CACHE_FILE" ]; then
  gh issue list --assignee @me --state open --json number,title,labels,milestone > "$CACHE_FILE"
fi

# Use cached data
ISSUES=$(cat "$CACHE_FILE")

Notes

• Always verify clean state before starting new work
• Read all related issues for full context
• Check spec completeness before implementation
• Update tracking files immediately after branch creation
• Consider dependencies when selecting issues
• Prefer current sprint issues over future work
• Validate specs exist and are complete
• Note any setup requirements (npm install, prisma generate, etc.)