gh-coalesce-labs-catalyst-plugins-dev/commands/cycle_review.md

description, category, tools, model, version, status

description	category	tools	model	version	status
Review cycle progress and identify blockers using Linearis and GitHub	project-task-management	Bash(linearis *), Bash(gh *), Read, Write, TodoWrite	inherit	1.0.0	placeholder

Cycle Review

Status: Placeholder for v1.0 - Full implementation coming in future release

Planned Functionality

This command will help you review cycle progress by:

1. Fetching active cycle details
2. Calculating completion percentage by status
3. Identifying blocked tickets
4. Generating velocity metrics
5. Creating cycle summary report

Current Workaround

Use Linearis CLI directly:

# Get active cycle with tickets
linearis cycles read "Sprint 2025-10" --team TEAM

# List tickets by status (use cycles read to get all issues, then filter)
linearis cycles read "Sprint 2025-10" --team TEAM | \
  jq '.issues[] | select(.state.name == "In Progress")'
linearis cycles read "Sprint 2025-10" --team TEAM | \
  jq '.issues[] | select(.state.name == "Done")'

# Calculate completion manually (count tickets)

Example Workflow

# 1. Get active cycle info
CYCLE=$(linearis cycles list --team ENG --active | jq -r '.[0].name')
echo "Active cycle: $CYCLE"

# 2. Get all tickets in cycle
linearis issues list --team ENG | \
  jq --arg cycle "$CYCLE" '.[] | select(.cycle.name == $cycle)'

# 3. Count by status (use cycles read to get issues)
CYCLE_DATA=$(linearis cycles read "$CYCLE" --team ENG)

echo "Backlog:"
echo "$CYCLE_DATA" | jq '[.issues[] | select(.state.name == "Backlog")] | length'

echo "In Progress:"
echo "$CYCLE_DATA" | jq '[.issues[] | select(.state.name == "In Progress")] | length'

echo "Done:"
echo "$CYCLE_DATA" | jq '[.issues[] | select(.state.name == "Done")] | length'

# 4. Calculate completion percentage
# total_tickets = backlog + in_progress + done
# completion = (done / total_tickets) * 100

# 5. Find blocked tickets (use cycles read)
linearis cycles read "$CYCLE" --team ENG | \
  jq '.issues[] | select(.state.name == "Blocked") | {id, title, blockedReason}'

# 6. Review PRs merged during cycle
# Get cycle start date (example: 2 weeks ago)
CYCLE_START=$(date -v-14d +%Y-%m-%d)

# List all PRs merged during cycle
gh pr list --state merged --search "merged:>=$CYCLE_START" \
  --json number,title,author,mergedAt --jq \
  '.[] | "\(.mergedAt | split("T")[0]) - \(.author.login): \(.title)"'

# 7. Identify active contributors
gh pr list --state merged --search "merged:>=$CYCLE_START" \
  --json author --jq '[.[].author.login] | group_by(.) | map({author: .[0], count: length}) | sort_by(-.count)'

# 8. Check open PRs (work in progress)
gh pr list --state open --json number,title,author,createdAt,isDraft | \
  jq '.[] | {author: .author.login, title, days_open: ((now - (.createdAt | fromdateiso8601)) / 86400 | floor), draft: .isDraft}'

# 9. Find work without Linear tickets
# Compare PR titles with Linear ticket IDs (TEAM-XXX pattern)
gh pr list --state merged --search "merged:>=$CYCLE_START" \
  --json number,title --jq '.[] | select(.title | test("TEAM-[0-9]+") | not) | {number, title}'

Future Implementation

When fully implemented, this command will:

• Automated metrics - Calculate completion, velocity, cycle time
• Status breakdown - Show tickets grouped by status with percentages
• Blocker identification - Highlight blocked tickets with reasons
• Trend analysis - Compare to previous cycles
• Risk assessment - Identify at-risk tickets (large, old, no progress)
• PR-based activity tracking - Analyze GitHub PR data to:
  • Identify who completed what work during the cycle
  • Find work done without Linear tickets (untracked work)
  • Calculate actual velocity based on merged PRs
  • Show contributor activity breakdown
  • Flag stale PRs that need attention
• Work reconciliation - Match PRs to Linear tickets, flag mismatches
• Team contribution report - Show per-person breakdown of PRs and tickets
• Summary generation - Create review document in thoughts/
• Burndown visualization - Show progress over time (text-based chart)

Track progress at: https://github.com/coalesce-labs/catalyst/issues

Configuration

Uses .claude/config.json:

{
  "linear": {
    "teamKey": "ENG",
    "defaultTeam": "Backend"
  }
}

Tips

• Review mid-cycle to course-correct
• Review end-of-cycle for retrospectives
• Track blockers daily - don't wait for review
• Compare velocity across cycles for capacity planning
• Document lessons learned for process improvement
• Celebrate wins - acknowledge team progress
• Use PR data to understand actual work:
  • Merged PRs show completed work (even if not in Linear)
  • Open PRs show current work in progress
  • PR activity reveals team contribution patterns
  • Missing ticket references indicate process gaps
• Reconcile Linear and GitHub regularly to ensure all work is tracked