Issue Lifecycle Skill | Agent Skills

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:

| Moment | Update Type | |--------|-------------| | Starting work | Status → In Progress | | Hitting a blocker | Comment explaining blocker | | Making a decision | Comment documenting decision | | Discovering new information | Comment with findings | | Completing acceptance criterion | Check off in body | | Completing verification | Post verification report | | Raising PR | Link PR to issue | | Work complete | Status → Done |

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:

Read current issue body
Find the criterion checkbox
Change - [ ] to - [x]
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:

When starting - "Starting work on this issue"
When blocked - Document the blocker immediately
When unblocked - Document resolution
When PR created - Link the PR
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

| Anti-Pattern | Problem | |--------------|---------| | Batch updates at end | No visibility during work | | "Made progress" comments | Not specific enough | | Updating only on success | Failures need documentation too | | Skipping blocker documentation | Lost context on what went wrong | | Closing without verification | Must verify before closing |

Do This Instead

| Good Pattern | Benefit | |--------------|---------| | Update as you go | Real-time visibility | | Specific progress notes | Clear record of what happened | | Document failures | Learn from problems | | Document blockers immediately | Faster unblocking | | Verification before close | Ensures quality |

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:

| Field | When to Update | |-------|----------------| | Status | When work state changes | | Verification | After running verification | | Criteria Met | After checking off criteria | | Last Verified | After verification runs |

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

Agent Skills: Issue Lifecycle

Skill Files