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

name, description, tools, model

name	description	tools	model
gh-project-view	View project details, items, and status with comprehensive reporting	Bash, Read, Write	inherit

View GitHub Project

This command provides comprehensive views of GitHub Projects with detailed reporting and analysis.

Instructions

Step 1: Identify the Project

Ask the user which project they want to view. Options:

1. By Name: "Sprint 5", "Q1 Roadmap", etc.
2. By Number: Project #3
3. Interactive: List all projects and let user choose

If listing projects:

gh project list --owner "@me" --format json | python3 -c "
import json, sys
projects = json.load(sys.stdin)
for p in projects:
    print(f\"#{p.get('number')} - {p.get('title')}\")
"

For organization projects:

gh project list --owner "org-name" --format json | python3 -c "
import json, sys
projects = json.load(sys.stdin)
for p in projects:
    print(f\"#{p.get('number')} - {p.get('title')}\")
"

Step 2: Get Project Details

Fetch comprehensive project information:

# Get project metadata
PROJECT_DATA=$(gh project view <number> --owner "<owner>" --format json)

# Parse key details using Python (safer than jq)
PROJECT_ID=$(echo "$PROJECT_DATA" | python3 -c "import json, sys; print(json.load(sys.stdin).get('id', ''))")
PROJECT_TITLE=$(echo "$PROJECT_DATA" | python3 -c "import json, sys; print(json.load(sys.stdin).get('title', ''))")
PROJECT_URL=$(echo "$PROJECT_DATA" | python3 -c "import json, sys; print(json.load(sys.stdin).get('url', ''))")
CREATED_AT=$(echo "$PROJECT_DATA" | python3 -c "import json, sys; print(json.load(sys.stdin).get('createdAt', ''))")
UPDATED_AT=$(echo "$PROJECT_DATA" | python3 -c "import json, sys; print(json.load(sys.stdin).get('updatedAt', ''))")

Step 3: Get Project Fields

Fetch all custom fields:

FIELDS=$(gh project field-list <number> --owner "<owner>" --format json --limit 50)

# Parse field details using Python
echo "$FIELDS" | python3 -c "
import json, sys
fields = json.load(sys.stdin)
for field in fields:
    print(f\"- {field.get('name')} ({field.get('dataType')})\")
"

Step 4: Get Project Items

Fetch all items with their field values:

ITEMS=$(gh project item-list <number> --owner "<owner>" --format json --limit 100)

# Count total items using Python
ITEM_COUNT=$(echo "$ITEMS" | python3 -c "import json, sys; data=json.load(sys.stdin); print(len(data.get('items', [])))")

Step 5: Analyze Item Distribution

Generate comprehensive statistics:

Status Distribution

# Save items to temp file for helper processing
echo "$ITEMS" > /tmp/gh_items.json

# Use Python helper to count by field
python3 -c "
import json, sys
with open('/tmp/gh_items.json') as f:
    data = json.load(f)
    items = data.get('items', [])

    # Count by Status
    status_counts = {}
    for item in items:
        for fv in item.get('fieldValues', []):
            if fv.get('name') == 'Status':
                status = fv.get('name') or 'Unset'
                status_counts[status] = status_counts.get(status, 0) + 1
                break

    for status, count in sorted(status_counts.items()):
        print(f'  {status}: {count}')
"

Priority Distribution

python3 -c "
import json
with open('/tmp/gh_items.json') as f:
    data = json.load(f)
    items = data.get('items', [])

    # Count by Priority
    priority_counts = {}
    for item in items:
        for fv in item.get('fieldValues', []):
            if fv.get('name') == 'Priority':
                priority = fv.get('name') or 'Unset'
                priority_counts[priority] = priority_counts.get(priority, 0) + 1
                break

    for priority, count in sorted(priority_counts.items()):
        print(f'  {priority}: {count}')
"

Item Types

# Count issues vs PRs vs drafts using Python
ISSUE_COUNT=$(python3 -c "import json; data=json.load(open('/tmp/gh_items.json')); print(len([i for i in data.get('items', []) if i.get('content', {}).get('type') == 'Issue']))")
PR_COUNT=$(python3 -c "import json; data=json.load(open('/tmp/gh_items.json')); print(len([i for i in data.get('items', []) if i.get('content', {}).get('type') == 'PullRequest']))")
DRAFT_COUNT=$(python3 -c "import json; data=json.load(open('/tmp/gh_items.json')); print(len([i for i in data.get('items', []) if i.get('content', {}).get('type') == 'DraftIssue']))")

Step 6: Identify Items Requiring Attention

High Priority Items Not Started

# P0/P1 items in Backlog or Todo using Python
python3 -c "
import json
with open('/tmp/gh_items.json') as f:
    data = json.load(f)
    items = data.get('items', [])

    for item in items:
        priority = None
        status = None

        for fv in item.get('fieldValues', []):
            if fv.get('name') == 'Priority':
                priority = fv.get('name')
            elif fv.get('name') == 'Status':
                status = fv.get('name')

        # Check if P0 or P1 and in Backlog or Todo
        if priority in ['P0', 'P1'] and status in ['Backlog', 'Todo']:
            content = item.get('content', {})
            number = content.get('number', 'draft')
            title = content.get('title', 'Untitled')
            print(f'  - #{number} {title}')
"

Stale Items (In Progress > 7 days)

THRESHOLD_DATE=$(date -v-7d +%Y-%m-%d 2>/dev/null || date -d '7 days ago' +%Y-%m-%d)

python3 -c "
import json
from datetime import datetime, timedelta

with open('/tmp/gh_items.json') as f:
    data = json.load(f)
    items = data.get('items', [])
    threshold = datetime.now() - timedelta(days=7)

    for item in items:
        status = None
        for fv in item.get('fieldValues', []):
            if fv.get('name') == 'Status':
                status = fv.get('name')
                break

        if status in ['In Progress', 'In Review']:
            content = item.get('content', {})
            updated_str = content.get('updatedAt', '')

            if updated_str:
                try:
                    updated_at = datetime.fromisoformat(updated_str.replace('Z', '+00:00'))
                    if updated_at < threshold:
                        number = content.get('number', 'draft')
                        title = content.get('title', 'Untitled')
                        updated_date = updated_str.split('T')[0]
                        days_old = (datetime.now() - updated_at).days
                        print(f'  - #{number} {title} (updated: {updated_date}, {days_old} days ago)')
                except:
                    pass
"

Items in Review

python3 -c "
import json
with open('/tmp/gh_items.json') as f:
    data = json.load(f)
    items = data.get('items', [])

    for item in items:
        status = None
        for fv in item.get('fieldValues', []):
            if fv.get('name') == 'Status':
                status = fv.get('name')
                break

        if status == 'In Review':
            content = item.get('content', {})
            number = content.get('number', 'draft')
            title = content.get('title', 'Untitled')
            print(f'  - #{number} {title}')
"

Step 7: Generate Comprehensive Report

Present results in a clear, scannable format:

# Project Report: [Project Title]

**Project #[Number]** | [Owner] | [URL]
Created: [Date] | Last Updated: [Date]

---

## Summary Statistics

- **Total Items**: [count]
- **Issues**: [count]
- **Pull Requests**: [count]
- **Draft Items**: [count]

---

## Item Distribution

### By Status
[Status distribution with counts]

### By Priority
[Priority distribution with counts]

---

## Items by Status

### Backlog ([count])
[List of backlog items with priority indicators]

### In Progress ([count])
[List of in-progress items with assignees if available]

### In Review ([count])
[List of items in review]

### Done ([count])
[Recently completed items]

---

## Items Requiring Attention

### 🚨 High Priority Not Started
[P0/P1 items in Backlog/Todo]

### ⚠️ Stale Items (In Progress > 7 days)
[List with last update dates]

### 👀 Awaiting Review
[Items in Review status]

### 🔍 Missing Priority
[Items without priority assignment]

---

## Field Summary

### Custom Fields
[List all custom fields with their types]

---

## Quick Actions

- Add items: `/gh-item-add`
- Update status: Use project-manager agent
- Triage backlog: `/gh-project-triage`
- Generate status report: `/gh-project-status`

---

## Project Health

[Overall assessment of project health based on metrics]
- Item distribution balance
- Priority coverage
- Stale item count
- Workflow bottlenecks

Step 8: Offer Drill-Down Options

Ask the user if they want to see:

• Specific items by status or priority
• Details of particular items
• Field values for all items
• Items assigned to specific person
• Items in specific iteration/sprint

View Modes

Support different view modes based on user needs:

Quick View

• Project title and number
• Total item count
• Status distribution only

Standard View (default)

• All summary statistics
• Status and priority distributions
• Items requiring attention

Detailed View

• Everything from standard view
• Individual item listings by status
• Field analysis
• Health metrics
• Recommendations

Custom View

Ask user what specific information they need:

• Filter by field values
• Show only certain item types
• Focus on specific time ranges
• Compare iterations/sprints

Important Notes

• Use --format json for all gh commands to enable parsing
• Handle missing fields gracefully (not all projects have same fields)
• Limit item fetching to 100 by default, offer pagination for larger projects
• Format dates consistently (YYYY-MM-DD)
• Use emoji sparingly for visual hierarchy
• Make URLs clickable where possible

Definition of Done

• Project identified (by name or number)
• Project metadata retrieved
• Fields listed and parsed
• Items fetched and analyzed
• Status distribution calculated
• Priority distribution calculated
• Items requiring attention identified
• Comprehensive report generated
• Drill-down options offered
• Report is clear, scannable, and actionable

Error Handling

• If project not found: List available projects, ask user to choose
• If no items: Report empty project, offer to add items
• If fields missing: Handle gracefully, report field setup status
• If API rate limit hit: Advise user to wait, show partial results
• If authentication fails: Check gh auth status, guide to refresh

Output Format Options

Ask user preference:

1. Markdown (default): Rich formatted text for terminal/web
2. JSON: Machine-readable for scripting
3. CSV: Export to spreadsheet
4. Summary: One-line overview for quick checks

Remember: A good project view provides both overview and insight, enabling users to understand status at a glance and identify action items immediately.