gh-yebot-rad-cc-plugins-plugins-github-project-manager/commands/gh-project-status.md

name, description, tools, model

name	description	tools	model
gh-project-status	Generate comprehensive status report of project progress and metrics	Bash, Read, Write	inherit

Generate Project Status Report

This command generates comprehensive status reports for GitHub Projects with metrics, insights, and actionable items.

Instructions

Step 1: Identify Project and Timeframe

Ask the user:

1. Which project to report on (name or number)
2. Timeframe for analysis (optional):
   • Current sprint/iteration
   • Last 7 days
   • Last 30 days
   • All time (default)

Step 2: Gather Project Data

Collect comprehensive project information:

# Get project metadata
PROJECT_DATA=$(gh project view <number> --owner "@me" --format json)
PROJECT_TITLE=$(echo $PROJECT_DATA | jq -r '.title')
PROJECT_URL=$(echo $PROJECT_DATA | jq -r '.url')

# Get all fields
FIELDS=$(gh project field-list <number> --owner "@me" --format json --limit 50)

# Get all items
ITEMS=$(gh project item-list <number> --owner "@me" --format json --limit 100)
TOTAL_ITEMS=$(echo $ITEMS | jq '.items | length')

Step 3: Calculate Core Metrics

Status Distribution

STATUS_METRICS=$(echo $ITEMS | jq -r '
  [.items[].fieldValues[] | select(.name=="Status")] |
  group_by(.name) |
  map({
    status: .[0].name,
    count: length,
    percentage: ((length / ('$TOTAL_ITEMS' | tonumber)) * 100 | floor)
  })
')

Priority Breakdown

PRIORITY_METRICS=$(echo $ITEMS | jq -r '
  [.items[].fieldValues[] | select(.name=="Priority")] |
  group_by(.name) |
  map({
    priority: .[0].name,
    count: length
  })
')

Item Types

ISSUE_COUNT=$(echo $ITEMS | jq '[.items[] | select(.content.type=="Issue")] | length')
PR_COUNT=$(echo $ITEMS | jq '[.items[] | select(.content.type=="PullRequest")] | length')
DRAFT_COUNT=$(echo $ITEMS | jq '[.items[] | select(.content.type=="DraftIssue")] | length')

Step 4: Identify Critical Items

Blockers & High Priority

# P0 items (critical)
P0_ITEMS=$(echo $ITEMS | jq -r '
  .items[] |
  select(.fieldValues[] | select(.name=="Priority" and .name=="P0")) |
  {
    title: .content.title,
    number: .content.number,
    status: (.fieldValues[] | select(.name=="Status") | .name),
    url: .content.url
  }
')

P0_COUNT=$(echo $P0_ITEMS | jq -s 'length')

# P1 items not in progress
P1_TODO=$(echo $ITEMS | jq -r '
  .items[] |
  select(
    (.fieldValues[] | select(.name=="Priority" and .name=="P1")) and
    (.fieldValues[] | select(.name=="Status" and (.name=="Backlog" or .name=="Todo")))
  ) |
  {
    title: .content.title,
    number: .content.number,
    status: (.fieldValues[] | select(.name=="Status") | .name)
  }
')

P1_TODO_COUNT=$(echo $P1_TODO | jq -s 'length')

Stale Items

# Items in progress > 7 days without update
THRESHOLD_DATE=$(date -v-7d +%Y-%m-%d)

STALE_ITEMS=$(echo $ITEMS | jq -r --arg threshold "$THRESHOLD_DATE" '
  .items[] |
  select(
    (.fieldValues[] | select(.name=="Status" and (.name=="In Progress" or .name=="In Review"))) and
    (.content.updatedAt | split("T")[0] < $threshold)
  ) |
  {
    title: .content.title,
    number: .content.number,
    status: (.fieldValues[] | select(.name=="Status") | .name),
    lastUpdated: (.content.updatedAt | split("T")[0]),
    daysSinceUpdate: (now - (.content.updatedAt | fromdateiso8601)) / 86400 | floor
  }
')

STALE_COUNT=$(echo $STALE_ITEMS | jq -s 'length')

Items in Review

REVIEW_ITEMS=$(echo $ITEMS | jq -r '
  .items[] |
  select(.fieldValues[] | select(.name=="Status" and .name=="In Review")) |
  {
    title: .content.title,
    number: .content.number,
    type: .content.type,
    url: .content.url
  }
')

REVIEW_COUNT=$(echo $REVIEW_ITEMS | jq -s 'length')

Step 5: Calculate Velocity (if applicable)

If project has Story Points or similar estimation:

# Completed items with story points
COMPLETED_POINTS=$(echo $ITEMS | jq '
  [.items[] |
   select(.fieldValues[] | select(.name=="Status" and .name=="Done")) |
   .fieldValues[] |
   select(.name=="Story Points") |
   .number
  ] | add // 0
')

# In progress points
IN_PROGRESS_POINTS=$(echo $ITEMS | jq '
  [.items[] |
   select(.fieldValues[] | select(.name=="Status" and .name=="In Progress")) |
   .fieldValues[] |
   select(.name=="Story Points") |
   .number
  ] | add // 0
')

# Total estimated points
TOTAL_POINTS=$(echo $ITEMS | jq '
  [.items[] |
   .fieldValues[] |
   select(.name=="Story Points") |
   .number
  ] | add // 0
')

# Completion percentage
if [ "$TOTAL_POINTS" -gt 0 ]; then
  COMPLETION_PCT=$(echo "scale=1; ($COMPLETED_POINTS / $TOTAL_POINTS) * 100" | bc)
else
  COMPLETION_PCT="N/A"
fi

Step 6: Analyze Health Indicators

Calculate project health score based on:

# Work distribution (ideal: balanced across statuses)
# Priority coverage (good: all items have priority)
# Stale item ratio (good: < 10% stale)
# Review bottleneck (warning: > 5 items in review)
# P0/P1 attention (critical: all P0/P1 should be active)

UNPRIORITIZED=$(echo $ITEMS | jq '
  [.items[] |
   select(.fieldValues[] | select(.name=="Priority") | not)
  ] | length
')

UNPRIORITIZED_PCT=$(echo "scale=1; ($UNPRIORITIZED / $TOTAL_ITEMS) * 100" | bc)

# Health score (0-100)
HEALTH_SCORE=100
[ "$STALE_COUNT" -gt $(echo "$TOTAL_ITEMS * 0.1" | bc | cut -d. -f1) ] && HEALTH_SCORE=$((HEALTH_SCORE - 20))
[ "$REVIEW_COUNT" -gt 5 ] && HEALTH_SCORE=$((HEALTH_SCORE - 15))
[ "$P1_TODO_COUNT" -gt 3 ] && HEALTH_SCORE=$((HEALTH_SCORE - 15))
[ "$UNPRIORITIZED" -gt 0 ] && HEALTH_SCORE=$((HEALTH_SCORE - 10))

Step 7: Generate Comprehensive Report

Present the analysis in a clear, executive-friendly format:

# Project Status Report
## [Project Title]

**Generated**: [Current Date/Time]
**Project**: #[Number] | [URL]
**Timeframe**: [Specified timeframe or "All time"]

---

## Executive Summary

**Overall Health**: [Excellent/Good/Fair/Poor] ([Health Score]/100)

**Key Metrics**:
- Total Items: [count]
- Completion: [X]% ([Completed]/[Total] points) [if applicable]
- Active Work: [In Progress count] items
- Awaiting Review: [Review count] items
- Blocked/Critical: [P0 count] items

**Status**: [1-2 sentence summary of project state]

---

## 📊 Item Distribution

### By Status
| Status | Count | Percentage |
|--------|-------|------------|
[For each status: | Status | X | Y% |]
| **Total** | **[Total]** | **100%** |

### By Priority
| Priority | Count | In Progress | Done |
|----------|-------|-------------|------|
[For each priority: | PX | X | Y | Z |]

### By Type
- Issues: [count]
- Pull Requests: [count]
- Draft Items: [count]

---

## 🎯 Velocity & Progress

[If story points available:]
- **Sprint Goal**: [X] points
- **Completed**: [Y] points ([Z]%)
- **In Progress**: [A] points
- **Remaining**: [B] points

**Projected Completion**: [On track / At risk / Behind]

[Visual progress bar:]

Backlog Todo In Progress Review Done ▓ ▓ ▓ ▓ ████████ [X] [Y] [Z] [A] [B]

---

## ⚠️ Items Requiring Attention

### 🚨 Critical (P0) - [count]
[If any P0 items exist, list them with status:]
- #[number] [title] - Status: [status]
[Otherwise: ✅ No critical items]

### ⏰ High Priority Not Started (P1) - [count]
[If any P1 in Backlog/Todo:]
- #[number] [title] - [status]
[Otherwise: ✅ All P1 items are in progress or done]

### 🐌 Stale Items (>7 days) - [count]
[If any stale items:]
- #[number] [title] - In Progress for [X] days
[Otherwise: ✅ No stale items]

### 👀 Awaiting Review - [count]
[If items in review:]
- #[number] [title] - [type] - [URL]
[Otherwise: ✅ No items in review]

### 🏷️ Missing Priority - [count]
[If unprioritized items exist:]
- [X]% of items lack priority assignment
- Action: Run `/gh-project-triage` to assign priorities
[Otherwise: ✅ All items prioritized]

---

## 📈 Trends & Insights

### Work Distribution
[Analysis of status distribution:]
- Healthy backlog: [Yes/No] ([X] items ready for work)
- Work in progress: [Appropriate/Too high/Too low] ([Y] items)
- Review bottleneck: [Yes/No] ([Z] items awaiting review)

### Priority Balance
- Critical items: [Appropriate/High] attention
- High priority: [Well-managed/Needs attention]
- Backlog refinement: [Current/Overdue]

### Completion Rate
[If velocity data available:]
- Current sprint: [X]% complete
- Average velocity: [Y] points/sprint
- Projected completion: [Date or "On track"]

---

## 🎬 Recommended Actions

1. **Immediate** (Do today):
   [List urgent actions based on analysis, e.g.:]
   - Review and prioritize [X] P0 items
   - Unblock [Y] stale items in progress
   - Review [Z] PRs awaiting review

2. **Short-term** (This week):
   [List important actions:]
   - Triage [X] unprioritized items
   - Start work on [Y] P1 items in backlog
   - Archive [Z] completed items from last sprint

3. **Ongoing**:
   - Maintain < 5 items in review
   - Keep P0/P1 items actively progressing
   - Regular backlog refinement (weekly)

---

## 📅 Next Review

**Recommended**: [Date - 1 week from now]

**Focus areas for next review**:
- P0 item resolution
- Velocity trend
- Stale item reduction

---

## Quick Actions

- View project: [URL]
- Triage backlog: `/gh-project-triage`
- Add items: `/gh-item-add`
- Update items: Use project-manager agent

---

*Report generated by GitHub Project Manager plugin*

Step 8: Offer Drill-Down Options

After presenting the report, ask if the user wants:

• Detailed list of items in specific status
• Individual item analysis
• Trend comparison (if historical data available)
• Export report to file
• Share report (formatted for team distribution)

Advanced Analysis

Cycle Time Analysis

If timestamp data available, calculate:

• Average time from Todo → Done
• Average time in each status
• Bottleneck identification

Burndown Chart (text-based)

For sprint projects with story points:

Sprint Burndown (Story Points)

40 |•
35 | •
30 |  ••
25 |    ••
20 |      •••
15 |         ••
10 |           ••
 5 |             •
 0 |______________•____
   D1 D3 D5 D7 D9 D11 D13

Ideal: --- | Actual: •••

Team Contribution

If assignee data available:

Items by Team Member:
- Alice: 8 (5 done, 2 in progress, 1 in review)
- Bob: 6 (4 done, 2 in progress)
- Charlie: 5 (3 done, 2 in review)
- Unassigned: 12

Export Options

Markdown File

# Save report to file
cat > "project-status-$(date +%Y-%m-%d).md" <<EOF
[Report content]
EOF

CSV Export

# Export items to CSV
echo $ITEMS | jq -r '
  ["Title", "Number", "Status", "Priority", "Type", "URL"],
  (.items[] | [
    .content.title,
    .content.number // "draft",
    (.fieldValues[] | select(.name=="Status") | .name),
    (.fieldValues[] | select(.name=="Priority") | .name // "Unset"),
    .content.type,
    .content.url // ""
  ]) | @csv
' > project-items.csv

Important Notes

• Refresh Data: Fetch latest data at report time
• Caching: For large projects, consider caching field IDs
• Pagination: Handle projects with >100 items
• Privacy: Don't expose sensitive item details in team reports
• Frequency: Weekly status reports are typical
• Stakeholder Version: Create executive summary for non-technical stakeholders

Definition of Done

• Project identified and data fetched
• Core metrics calculated (status, priority, types)
• Critical items identified (P0, stale, blocked)
• Velocity calculated (if applicable)
• Health score determined
• Comprehensive report generated
• Actionable recommendations provided
• Drill-down options offered
• Export option offered if requested

Error Handling

• If no items: Report empty project, suggest adding items
• If missing fields: Handle gracefully, note in report
• If API limits hit: Show partial results, suggest retry
• If calculations fail: Use fallback values, note in report

Remember: A great status report tells a story - where we are, how we got here, and what we should do next. Make it scannable, actionable, and insightful.