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 --add-label "status:in-progress" --remove-label "status:todo"
gh issue comment $ARGUMENTS --body "Starting work on this issue."

# Create feature branch
git checkout -b issue/$ARGUMENTS-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): 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 --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): brief description" \
  --body "Closes #$ARGUMENTS

## Changes
- Change 1
- Change 2

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

# Update issue status
gh issue edit $ARGUMENTS --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

Rules (2)

Make small commits with issue references to maintain traceability and enable bisect — HIGH

Small Commits with Issue References

Commit after each logical step. Every commit references the issue number.

Incorrect:

# One giant commit at the end
git add .
git commit -m "implement feature"

Correct:

# Commit after each logical step
git commit -m "feat(#123): add user model and migration"
git commit -m "feat(#123): add authentication endpoint"
git commit -m "test(#123): add auth endpoint tests"

Key rules:

• One logical change per commit (schema, endpoint, tests = separate commits)
• Always include #N in the commit message to link to the issue
• Use conventional commit format: type(#N): description
• Commit before switching context — don't lose work in unstaged changes
• If a commit touches more than 3 files in different domains, it is probably too large

Run the start-work ceremony to establish branch traceability and team visibility — HIGH

Start Work Ceremony

Before writing any code, signal intent and create an isolated branch.

Incorrect:

# Jump straight into coding on main
git checkout main
# ... make changes ...
git commit -m "fix stuff"

Correct:

# 1. Update issue status
gh issue edit 123 --add-label "status:in-progress" --remove-label "status:todo"

# 2. Comment your intent
gh issue comment 123 --body "Starting work on this issue."

# 3. Branch from default branch
git checkout main && git pull origin main
git checkout -b issue/123-add-user-auth

Key rules:

• Always pull latest default branch before branching
• Branch name format: issue/<number>-<brief-kebab-description>
• Label the issue before starting work — prevents duplicate effort
• Comment briefly what approach you plan to take