Issue Lifecycle

Issue Lifecycle

Overview

Update issues AS work happens, not in one dump at the end.

Core principle: The issue is the source of truth. Keep it current.

This skill is used THROUGHOUT work, not as a separate step.

When to Update

Update the issue at these moments:

Update Types

Status Updates (Project Field)

# Get item ID
ITEM_ID=$(gh project item-list [PROJECT_NUMBER] --owner @me \
  --format json | jq -r '.items[] | select(.content.number == [ISSUE_NUMBER]) | .id')

# Update status
gh project item-edit --project-id [PROJECT_ID] --id $ITEM_ID \
  --field-id [STATUS_FIELD_ID] \
  --single-select-option-id [NEW_STATUS_OPTION_ID]

Comment Updates

gh issue comment [ISSUE_NUMBER] --body "## Progress Update

**Time:** $(date -u +%Y-%m-%dT%H:%M:%SZ)

### Completed
- Implemented X
- Fixed Y

### In Progress
- Working on Z

### Blockers
- None

### Next Steps
- Will do A next"

Checkbox Updates (Acceptance Criteria)

When an acceptance criterion is met:

1. Read current issue body
2. Find the criterion checkbox
3. Change - [ ] to - [x]
4. Update the issue body

# Get current body
BODY=$(gh issue view [ISSUE_NUMBER] --json body -q '.body')

# Update checkbox (example with sed)
NEW_BODY=$(echo "$BODY" | sed 's/- \[ \] First criterion/- [x] First criterion/')

# Update issue
gh issue edit [ISSUE_NUMBER] --body "$NEW_BODY"

Update Frequency

Minimum Updates

At absolute minimum, update at these points:

1. When starting - "Starting work on this issue"
2. When blocked - Document the blocker immediately
3. When unblocked - Document resolution
4. When PR created - Link the PR
5. When complete - Final status update

Recommended Updates

For active work, update more frequently:

• After each significant step
• When making decisions that affect approach
• When discovering unexpected complexity
• Every 30-60 minutes of active work

What to Include in Updates

Progress Comments

## Progress Update - [TIME]

### Completed
- [What was done]

### Currently Working On
- [Active work]

### Decisions Made
- [Decision]: [Rationale]

### Issues Encountered
- [Issue]: [How resolved or current status]

### Next Steps
- [What comes next]

Decision Comments

## Decision: [Brief Title]

**Context:** [Why this decision was needed]

**Options Considered:**
1. [Option A] - [Pros/Cons]
2. [Option B] - [Pros/Cons]

**Decision:** [Chosen option]

**Rationale:** [Why this option was chosen]

Blocker Comments

## Blocked: [Brief Description]

**Blocked at:** [TIME]
**Blocking issue:** [What's preventing progress]

**What was tried:**
1. [Attempt 1]
2. [Attempt 2]

**Needs:** [What's needed to unblock]

**Impact:** [How this affects timeline/scope]

Anti-Patterns

Don't Do This

Do This Instead

Reading Issue History

Before starting work on any issue:

# View issue with all comments
gh issue view [ISSUE_NUMBER] --comments

# View timeline
gh issue view [ISSUE_NUMBER] --json timeline

Look for:

• Previous attempts
• Known blockers
• Decisions already made
• Related discussions

Project Field Updates

Keep these fields current:

Integration with Other Skills

This skill is used by:

• issue-driven-development - Throughout all steps
• acceptance-criteria-verification - Post verification reports
• error-recovery - Document failures

Checklist

For each work session, ensure:

• Issue status reflects current state
• Any blockers are documented
• Decisions are recorded
• Completed criteria are checked off
• Verification reports are posted
• PRs are linked