Refresh

• Verify it has the ready label
• If not, inform the user that this command is for refreshing ready issues
• Suggest /groom for issues that need initial grooming
• Skip to Step 2 with that issue number

If no issue number was provided:

1. Fetch issues with ready label:

   gh issue list --label ready --json number,title,labels,updatedAt --limit 20 | \
     jq 'sort_by(.updatedAt)'
   

2. If no issues found, inform the user and exit.

3. Present the issues and ask the user to select one:

   • Show oldest issues first (more likely to be stale)
   • Each option should include last updated date
   • Include "(oldest)" marker for the oldest issue

Step 2: Research Phase (REQUIRED)

This phase gathers information about the issue and compares it to the current codebase state.

1. Fetch full issue details and comments:

   gh issue view <number> --json number,title,body,labels,createdAt,updatedAt
   gh issue view <number> --comments
   

2. Parse issue structure:

   • Description: What needs to be done
   • Acceptance Criteria: The definition of done
   • Out of Scope: What to explicitly avoid

3. Identify referenced elements in the issue:

   • File paths mentioned
   • API endpoints or routes
   • Component names
   • Function/method names
   • Database tables or columns
   • Environment variables
   • External dependencies or packages

4. Check blocker status:

   • Look for "blocked by #X" or "depends on #X" references in the body or comments
   • For each blocker, check if it's closed:

   gh issue view <blocker-number> --json state,title
   

5. Compare issue expectations vs codebase reality:

   Use Glob, Grep, and Read tools to verify:

   • Referenced files still exist at the expected paths
   • APIs/patterns mentioned in the issue still apply
   • Any prerequisites mentioned have been implemented
   • Any new patterns or conventions that should be considered

Step 3: Analysis Phase

Based on research, identify staleness in these categories:

1. Completed Prerequisites:

• Blockers that are now closed
• Infrastructure that now exists
• Features that have been implemented

2. Outdated References:

• File paths that have changed or no longer exist
• API endpoints that have been modified
• Components that have been renamed or refactored
• Patterns that have been superseded

3. Changed Context:

• New patterns or conventions that should be followed
• Related features that have been added
• Dependencies that have been updated

4. Acceptance Criteria Changes:

• Criteria that are now automatically satisfied
• Criteria that need adjustment based on new reality
• Criteria that are no longer relevant

Step 4: Present Findings

Present findings to the user organized by category:

## Issue Freshness Analysis: #<number> - <title>

### Summary

[Overall assessment: Fresh / Minor Updates Needed / Significant Updates Needed]

### Completed Prerequisites

- [x] Blocker #X is now closed: [title]
- [x] [Feature/infrastructure] now exists

### Outdated References

- File `old/path.ts` has moved to `new/path.ts`
- API endpoint `/old` is now `/new`
- Pattern X has been replaced with pattern Y

### Changed Context

- New convention: [description]
- Related feature added: [description]

### Acceptance Criteria Review

- [ ] Criterion 1: Still valid
- [ ] Criterion 2: Needs update - [reason]
- [x] Criterion 3: Already satisfied by [implementation]

### Recommended Updates

[List specific changes to make to the issue]

If no staleness detected:

## Issue Freshness Analysis: #<number> - <title>

### Summary

This issue is still fresh and accurate.

- All file references are valid
- No completed blockers found
- Acceptance criteria are still appropriate
- Context matches current codebase state

No updates needed.

Step 5: User Decision

Ask the user to choose from these options:

• Apply updates: Edit the issue with proposed changes (only if updates recommended)
• Mark for re-grooming: Send back to needs-details for more significant rework
• Skip: No changes needed

Step 6: Apply Updates (if approved)

If "Apply updates":

• Update the issue body:

  gh issue edit <number> --body "<updated body>"
  

If "Mark for re-grooming":

1. Update labels:

   gh issue edit <number> --remove-label ready --add-label needs-details
   

2. Add comment explaining why:

   gh issue comment <number> --body "Sent back for re-grooming: [reason from user or analysis]"
   

Step 7: Summary

Provide a summary including:

• Issue number and title
• Freshness assessment (Fresh / Updated / Sent for re-grooming)
• Key changes made (if any)
• Link to the issue

Edge Cases

Issue Not Ready

If the selected issue doesn't have ready label:

This command is for refreshing `ready` issues.

Issue #X has label: [current labels]

Would you like to:
1. Run /groom to groom this issue first
2. Choose a different issue

No Ready Issues

If no ready issues exist:

No issues with the `ready` label found.

You can:
- Run /groom to prepare draft issues
- Check if issues exist with: gh issue list --limit 20

Blockers Still Open

If the issue references blockers that are still open:

• Include this prominently in findings
• Note that some criteria may not be verifiable until blockers close
• Suggest waiting or working on blockers first

Notes

• ALWAYS complete the research phase before presenting findings
• Do NOT make changes without user approval
• Preserve existing issue content - only update stale sections
• Be conservative with "still fresh" assessments - when in doubt, flag for review
• The goal is verification, not re-grooming. Suggest /groom for major rework