zhongwei/gh-coalesce-labs-catalyst-plugins-pm

Files

Zhongwei Li fa2c495eac Initial commit

2025-11-29 18:14:44 +08:00

5.8 KiB

Raw Permalink Blame History

description, category, tools, model, version

description	category	tools	model	version
Groom Linear backlog to identify orphaned issues, incorrect project assignments, and health issues	pm	Task, Read, Write	inherit	1.0.0

Groom Backlog Command

Comprehensive backlog health analysis that identifies:

Issues without projects (orphaned)
Issues in wrong projects (misclassified)
Issues without estimates
Stale issues (no activity >30 days)
Duplicate issues (similar titles)

Prerequisites Check

# 1. Validate thoughts system (REQUIRED)
if [[ -f "scripts/validate-thoughts-setup.sh" ]]; then
  ./scripts/validate-thoughts-setup.sh || exit 1
else
  # Inline validation if script not found
  if [[ ! -d "thoughts/shared" ]]; then
    echo "❌ ERROR: Thoughts system not configured"
    echo "Run: ./scripts/humanlayer/init-project.sh . {project-name}"
    exit 1
  fi
fi

# 2. Determine script directory with fallback
if [[ -n "${CLAUDE_PLUGIN_ROOT}" ]]; then
  SCRIPT_DIR="${CLAUDE_PLUGIN_ROOT}/scripts"
else
  # Fallback: resolve relative to this command file
  SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)/scripts"
fi

# 3. Check PM plugin prerequisites
if [[ -f "${SCRIPT_DIR}/check-prerequisites.sh" ]]; then
  "${SCRIPT_DIR}/check-prerequisites.sh" || exit 1
else
  echo "⚠️ Prerequisites check skipped (script not found at: ${SCRIPT_DIR})"
fi

Process

Step 1: Spawn Research Agent

# Determine script directory with fallback
if [[ -n "${CLAUDE_PLUGIN_ROOT}" ]]; then
  SCRIPT_DIR="${CLAUDE_PLUGIN_ROOT}/scripts"
else
  # Fallback: resolve relative to this command file
  SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)/scripts"
fi

source "${SCRIPT_DIR}/pm-utils.sh"
TEAM_KEY=$(get_team_key)

Use Task tool with catalyst-dev:linear-research agent:

Prompt: "Get all backlog issues for team ${TEAM_KEY} including issues with no cycle assignment"
Model: haiku

Step 2: Spawn Analysis Agent

Use Task tool with backlog-analyzer agent:

Input: Backlog issues JSON from research

Output: Structured recommendations with:

Orphaned issues (no project)
Misplaced issues (wrong project)
Stale issues (>30 days)
Potential duplicates
Missing estimates

Step 3: Generate Grooming Report

Create markdown report with sections:

Orphaned Issues (no project):

## 🏷️ Orphaned Issues (No Project Assignment)

### High Priority
- **TEAM-456**: "Add OAuth support"
  - **Suggested Project**: Auth & Security
  - **Reasoning**: Mentions authentication, OAuth, security tokens
  - **Action**: Move to Auth project

[... more issues ...]

### Medium Priority
[... issues ...]

Misplaced Issues (wrong project):

## 🔄 Misplaced Issues (Wrong Project)

- **TEAM-123**: "Fix dashboard bug" (currently in: API)
  - **Should be in**: Frontend
  - **Reasoning**: UI bug, no backend changes mentioned
  - **Action**: Move to Frontend project

Stale Issues (>30 days inactive):

## 🗓️ Stale Issues (No Activity >30 Days)

- **TEAM-789**: "Investigate caching" (last updated: 45 days ago)
  - **Action**: Review and close, or assign to current cycle

Duplicates (similar titles):

## 🔁 Potential Duplicates

- **TEAM-111**: "User authentication bug"
- **TEAM-222**: "Authentication not working"
  - **Similarity**: 85%
  - **Action**: Review and merge

Missing Estimates:

## 📊 Issues Without Estimates

- TEAM-444: "Implement new feature"
- TEAM-555: "Refactor old code"
  - **Action**: Add story point estimates

Step 4: Interactive Review

Present recommendations and ask user:

📋 Backlog Grooming Report Generated

Summary:
  🏷️ Orphaned: 12 issues
  🔄 Misplaced: 5 issues
  🗓️ Stale: 8 issues
  🔁 Duplicates: 3 pairs
  📊 No Estimates: 15 issues

Would you like to:
1. Review detailed report (opens in editor)
2. Apply high-confidence recommendations automatically
3. Generate Linear update commands for manual execution
4. Skip (report saved for later)

Step 5: Generate Update Commands

If user chooses option 3, generate batch update script:

#!/usr/bin/env bash
# Backlog grooming updates - Generated 2025-01-27

# Move TEAM-456 to Auth project
linearis issues update TEAM-456 --project "Auth & Security"

# Move TEAM-123 to Frontend project
linearis issues update TEAM-123 --project "Frontend"

# Close stale issue TEAM-789
linearis issues update TEAM-789 --state "Canceled"
linearis comments create TEAM-789 --body "Closing stale issue (>30 days inactive)"

# [... more commands ...]

echo "✅ Backlog grooming updates applied"

# Save update script
UPDATE_SCRIPT="thoughts/shared/reports/backlog/$(date +%Y-%m-%d)-grooming-updates.sh"
mkdir -p "$(dirname "$UPDATE_SCRIPT")"
# [script contents saved here]
chmod +x "$UPDATE_SCRIPT"

Step 6: Save Report

REPORT_DIR="thoughts/shared/reports/backlog"
mkdir -p "$REPORT_DIR"

REPORT_FILE="$REPORT_DIR/$(date +%Y-%m-%d)-backlog-grooming.md"

# Write formatted report to file
cat > "$REPORT_FILE" << EOF
# Backlog Grooming Report - $(date +%Y-%m-%d)

[... formatted report content ...]
EOF

echo "✅ Report saved: $REPORT_FILE"

# Update workflow context
if [[ -f "${SCRIPT_DIR}/workflow-context.sh" ]]; then
  "${SCRIPT_DIR}/workflow-context.sh" add reports "$REPORT_FILE" null
fi

Success Criteria

Automated Verification:

All backlog issues fetched successfully
Agent analysis completes without errors
Report generated with all sections
Update script is valid bash syntax
Files saved to correct locations

Manual Verification:

Orphaned issues correctly identified
Project recommendations make sense
Stale issues are actually inactive
Duplicate detection has few false positives
Report is actionable and clear

5.8 KiB Raw Permalink Blame History