analyze-milestone

# Analyze Milestone Command

Generates a comprehensive **health report** for a project milestone.

**Reports Include**:
- 🟢🟡🔴 Health assessment with target date feasibility
- 📊 Progress metrics toward target date
- 🎯 Actionable takeaways (what needs attention NOW)
- ⚠️ Risk identification (behind schedule, blocked, at-risk)
- 💡 Specific recommendations (adjust timeline, reduce scope, etc.)

**Philosophy**: Provide insights and recommendations for milestone planning, not just data dumps.

## Prerequisites Check

```bash
# 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: Gather Configuration and Milestone Identifier

**Option A: User provides milestone name**
```bash
MILESTONE_NAME="Q1 Launch"
PROJECT_NAME="Mobile App"
```

**Option B: Interactive prompt**
```
Which milestone would you like to analyze?
- Milestone name: [user input]
- Project name (optional, helps scope lookup): [user input]
```

### Step 2: Spawn Research Agent

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

```
Prompt: "Get milestone '${MILESTONE_NAME}' details for project '${PROJECT_NAME}' with all issues (limit 100)"
Model: haiku (fast data gathering)
```

If milestone not found or ambiguous, report error and ask user to clarify.

### Step 3: Spawn Analysis Agent

Use Task tool with `milestone-analyzer` agent:

**Input**:
- Milestone data JSON from research task
- Current date: $(date +%Y-%m-%d)
- Project configuration (if available)

**Agent returns**:
Structured markdown with:
- Health score and target date feasibility
- Progress tracking (actual vs expected)
- Risk factors (target date, blockers, at-risk)
- Issue distribution
- Specific recommendations

### Step 4: Format Report

Format the analyzer output into final report:

```markdown
# Milestone Health Report: [Milestone Name]

**Project**: [Project Name]
**Target Date**: [YYYY-MM-DD] ([X] days remaining)
**Generated**: [YYYY-MM-DD HH:MM]

---

## 🟢/🟡/🔴 Health Assessment

**Takeaway**: [One-sentence summary with target date assessment]

**Current State**:
- Progress: X% complete (Y/Z issues done)
- Target: [YYYY-MM-DD] ([N] days remaining)
- Projected completion: [YYYY-MM-DD] (based on current velocity)
- Risk level: [On track / Behind by N days / Critical]

---

## 📊 Progress Tracking

[Progress bars, velocity, time remaining]

---

## ⚠️ Risks & Blockers

[Target date risks, blockers, at-risk issues]

---

## 💡 Recommendations

[Priority-ordered actions]

---

**Next Review**: [Suggested date based on target date proximity]
```

### Step 5: Save Report

**IMPORTANT: Document Storage Rules**
- ALWAYS write to `thoughts/shared/pm/reports/`
- NEVER write to `thoughts/searchable/` — this is a read-only search index

```bash
REPORT_DIR="thoughts/shared/pm/reports"
mkdir -p "$REPORT_DIR"

# Sanitize milestone name for filename
MILESTONE_SLUG=$(echo "$MILESTONE_NAME" | tr '[:upper:]' '[:lower:]' | tr ' ' '-')
REPORT_FILE="$REPORT_DIR/$(date +%Y-%m-%d)-${MILESTONE_SLUG}.md"

# Write formatted report
# ...

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" "${TICKET_ID:-null}"
fi
```

### Step 6: Display Summary

```
🎯 Milestone Health: [Milestone Name] - [🟢/🟡/🔴]

Target Date: [YYYY-MM-DD] ([X] days remaining)
Progress: ████████░░ [X]% ([Y]/[Z] issues)
Status: [On track / Behind by N days]

Priority Actions:
  1. [Action 1]
  2. [Action 2]
  3. [Action 3]

Full report: thoughts/shared/pm/reports/YYYY-MM-DD-milestone.md
```

## Success Criteria

### Automated Verification:
- [ ] Research agent fetches milestone data successfully
- [ ] Analyzer agent produces structured output
- [ ] Report file created in expected location
- [ ] No errors when milestone exists

### Manual Verification:
- [ ] Health score accurately reflects milestone state
- [ ] Target date feasibility is realistic
- [ ] Recommendations are specific and actionable
- [ ] Report guides PM to adjust timeline or scope if needed
- [ ] Works with different projects and milestone names