---
title: "Issue Progress Tracking"
description: "GitHub issue workflow ceremony using gh CLI — labels issues as in-progress, creates feature branches (issue/N-description), commits with issue references, posts progress comments, and links PRs with Closes #N. Keeps issues in sync with development work. Use when starting work on an issue, tracking progress, or completing work with a PR."
canonical: "https://orchestkit.yonyon.ai/docs/reference/skills/issue-progress-tracking"
---

# Issue Progress Tracking

GitHub issue workflow ceremony using gh CLI — labels issues as in-progress, creates feature branches (issue/N-description), commits with issue references, posts progress comments, and links PRs with Closes #N. Keeps issues in sync with development work. Use when starting work on an issue, tracking progress, or completing work with a PR.

<span className="badge badge-gray">Reference</span> <span className="badge badge-green">low</span>

> **Not directly invocable** — no slash command and no model auto-selection. An agent loads it explicitly via `Read()`.

<ContextualSkillSidebar slug="issue-progress-tracking" />

> **Issue Progress Tracking** GitHub issue workflow ceremony using gh CLI — labels issues as in-progress, creates feature branches (issue/N-description), commits with issue references, posts progress comments, and links PRs with Closes #N. Keeps issues in sync with development work. Use when starting work on an issue, tracking progress, or completing work with a PR.


# 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:

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

---

## Phase 1: Start Work

Label the issue and create a feature branch:

```bash
# 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/&lt;number&gt;-&lt;brief-description&gt;`
- 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:

```bash
# 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:

```bash
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:

```bash
# 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](rules/start-work-ceremony.md) | HIGH | Branch creation, label updates, initial comment |
| [Small Commits](rules/small-commits.md) | 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/&lt;N&gt;-desc` | Links branch to issue automatically |
| Commit reference | `type(#N):` | Conventional commits + issue linking |
| Progress comments | Manual | Keeps humans in the loop |

---

## 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:**
```bash
# One giant commit at the end
git add .
git commit -m "implement feature"
```

**Correct:**
```bash
# 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:**
```bash
# Jump straight into coding on main
git checkout main
# ... make changes ...
git commit -m "fix stuff"
```

**Correct:**
```bash
# 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/&lt;number&gt;-&lt;brief-kebab-description&gt;`
- Label the issue before starting work — prevents duplicate effort
- Comment briefly what approach you plan to take