Issue Progress Tracking
Ceremony guide for tracking GitHub issue progress via gh CLI. Ensures issues stay updated as work progresses from start to PR.
Quick Start
/ork:issue-progress-tracking 123
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
| Rule | Impact | What It Covers |
|---|---|---|
| Start Work Ceremony | HIGH | Branch creation, label updates, initial comment |
| Small Commits | HIGH | Atomic commits referencing issues |
Total: 2 rules across 2 categories
Key Decisions
| Decision | Choice | Rationale |
|---|---|---|
| Label prefix | status: |
Consistent with GitHub conventions |
| Branch format | issue/<N>-desc |
Links branch to issue automatically |
| Commit reference | type(#N): |
Conventional commits + issue linking |
| Progress comments | Manual | Keeps humans in the loop |
Common Mistakes
- Starting work without labeling — team loses visibility into who is working on what
- Giant commits at the end — makes review harder and history useless for bisect
- Forgetting to link PR to issue — issue stays open after merge
- Not updating labels on PR creation — issue shows "in-progress" during review
- Closing issues manually with
gh issue close— issues are closed ONLY by merging a PR withCloses #Nin the body. During work, comment progress withgh issue comment; never close directly.
Related Skills
ork:commit— Commit with conventional formatork:fix-issue— Full issue resolution workflowork:implement— Feature implementation with parallel agentsork:create-pr— Create pull requests
Converted and distributed by TomeVault — claim your Tome and manage your conversions.