Issue Progress Tracking

Issue Progress Tracking

Ceremony guide for tracking GitHub issue progress via gh CLI. Ensures issues stay updated as work progresses from start to PR.

Invocation

This skill is user-invocable: false and disable-model-invocation: true: there is no /ork: form and the model cannot auto-select it (#3313). An agent loads it explicitly by Reading this file's path:

${CLAUDE_PLUGIN_ROOT}/skills/issue-progress-tracking/SKILL.md

Phase 1: Start Work

Label the issue and create a feature branch:

# Move issue to in-progress
gh issue edit $ARGUMENTS[0] --add-label "status:in-progress" --remove-label "status:todo"
gh issue comment $ARGUMENTS[0] --body "Starting work on this issue."

# Create feature branch
git checkout -b issue/$ARGUMENTS[0]-brief-description

Rules:

• Always branch from the default branch (main/dev)
• Branch name format: issue/<number>-<brief-description>
• Never work directly on main/dev

Phase 2: During Work — Small Commits

Commit after each logical step, not at the end. Every commit references the issue:

# Each commit references the issue number
git commit -m "feat(#$ARGUMENTS[0]): add user model

Co-Authored-By: Claude <noreply@anthropic.com>"

Rules:

• One logical change per commit (atomic)
• Reference issue in every commit: type(#N): description
• Commit early and often — don't accumulate a massive diff

Phase 3: Report Progress (Long Implementations)

For multi-step work, post progress updates:

gh issue comment $ARGUMENTS[0] --body "Progress update:
- Completed: database schema, API endpoints
- In progress: frontend components
- Remaining: tests, documentation"

When to post updates:

• After completing a major milestone
• When blocked or changing approach
• Before stepping away from a long task

Phase 4: Complete Work

Create the PR and update labels:

# Create PR that closes the issue
gh pr create \
  --title "feat(#$ARGUMENTS[0]): brief description" \
  --body "Closes #$ARGUMENTS[0]

## Changes
- Change 1
- Change 2

## Test Plan
- [ ] Unit tests pass
- [ ] Manual verification"

# Update issue status
gh issue edit $ARGUMENTS[0] --add-label "status:in-review" --remove-label "status:in-progress"

Rules Quick Reference

Total: 2 rules across 2 categories

Key Decisions

Common Mistakes

1. Starting work without labeling — team loses visibility into who is working on what
2. Giant commits at the end — makes review harder and history useless for bisect
3. Forgetting to link PR to issue — issue stays open after merge
4. Not updating labels on PR creation — issue shows "in-progress" during review
5. Closing issues manually with gh issue close — issues are closed ONLY by merging a PR with Closes #N in the body. During work, comment progress with gh issue comment; never close directly.

Related Skills

• ork:commit — Commit with conventional format
• ork:fix-issue — Full issue resolution workflow
• ork:implement — Feature implementation with parallel agents
• ork:create-pr — Create pull requests