Auto-activated — this skill loads automatically when Claude detects matching context.

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

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