Smart PAC Update Status

Update ticket status, track progress, and trigger git workflow actions in your Product as Code project with validated state transitions.

When to Use This Command

Run this command when...

• You need to move a PAC ticket through its lifecycle: backlog, in-progress, review, blocked, done, or cancelled
• You want status changes to trigger git actions like branch creation for in-progress or PR suggestions for review
• You need to update the parent epic's progress tracking when individual tickets change state
• You want validated state transitions that prevent invalid moves like jumping from backlog directly to done
• You are tracking development progress and need timestamped status change history on tickets

Quick Start

Copy
# .claude/commands/smart-pac-update-status.yaml
name: Smart PAC Update Status
description: Update PAC ticket status with validated transitions and git integration
inputs:
  - name: ticket
    description: "Ticket ID to update"
  - name: status
    description: "New status value"

Copy
# Move a ticket to in-progress
claude "smart-pac-update-status --ticket TICKET-042 --status in-progress"

# Add a comment with the status change
claude "smart-pac-update-status --ticket TICKET-042 --status review --comment 'Ready for code review'"

Output:
  [load] Ticket TICKET-042: "Add login endpoint"
  [validate] Transition: backlog -> in-progress (valid)
  [update] Status changed to in-progress
  [git] Created branch: ticket/TICKET-042
  [epic] Updated epic-user-auth progress: 2/5 in-progress
  Done. Ticket TICKET-042 is now in-progress.

Core Concepts

Concept	Description
State Machine	Valid transitions enforced: backlog->in-progress->review->done, with blocked/cancelled as intermediate states
Git Integration	Status changes trigger git actions: branch creation, PR suggestions, merge prompts
Epic Rollup	Parent epic progress is automatically recalculated when child ticket status changes
Timestamped History	Every status change records a timestamp and optional comment in the ticket YAML
Interactive Selection	When no ticket ID is provided, displays a list of active tickets for selection

Valid Status Transitions:
  backlog ──────> in-progress ──────> review ──────> done
     │                │                  │
     │                ▼                  │
     │            blocked ───────────────┘
     │                │
     └────────> cancelled <──── (any state)

Configuration

Parameter	Type	Default	Description
ticket	string	interactive	Ticket ID to update, or omit for interactive selection
status	string	required	Target status: backlog, in-progress, review, blocked, done, cancelled
assignee	string	current	Reassign the ticket to a different team member
comment	string	""	Progress note appended to the ticket's history log
epic	string	all	Filter tickets by epic ID when using interactive selection

Best Practices

1. Transition in order -- Follow the natural flow from backlog through in-progress and review to done. Skipping states loses tracking granularity and makes velocity calculations unreliable.
2. Add comments on every transition -- A short note like "blocked on API access" or "tests passing, ready for review" creates a searchable history that helps during retrospectives.
3. Use blocked status instead of leaving in-progress -- When work stalls, explicitly marking a ticket as blocked surfaces impediments to the team rather than hiding them.
4. Filter by epic for focused updates -- Use --epic to narrow the interactive selection to tickets from a specific epic, especially in projects with dozens of active tickets.
5. Review epic progress after updates -- The command shows updated epic progress. Use this to decide if the epic is on track or needs additional tickets broken out.

Common Issues

1. Invalid state transition -- The command rejects transitions that violate the state machine (e.g., backlog to done). Move through intermediate states or use --force if the transition is intentional.
2. Ticket not found -- Ensure the ticket ID matches exactly, including case. List available tickets with find .pac/tickets/ -name "*.yaml" to verify the correct ID.
3. Epic progress not updating -- The ticket must reference a parent epic in its YAML metadata. If the epic field is missing or incorrect, the rollup calculation will skip that ticket.