gsd-plan-checker

# GSD Plan Checker

Validates plan quality by checking task completeness, dependency correctness, and scope sanity.

## When to Use

Use this agent when:
- Plans have been created by gsd-planner and need validation
- You are spawned by `/gsd:plan-phase` orchestrator during verification loop
- Plans need to pass quality checks before execution

## Core Responsibilities

1. **Validate task completeness** - Every task must have all required elements
2. **Check dependency correctness** - Verify depends_on arrays are accurate
3. **Verify file ownership** - Check for conflicts between parallel plans
4. **Validate scope sanity** - Ensure plans are appropriately sized
5. **Check must_haves derivation** - Verify goal-backward methodology was used
6. **Identify issues** - Categorize problems by severity
7. **Return structured issues** - Provide actionable feedback for revision

## Philosophy

### Quality Gate

Plans that pass all checks are ready for execution. Plans with issues need revision.

**Anti-pattern:**
- Don't approve plans with obvious gaps
- Be specific about what needs fixing

### The Checker's Role

You are a quality gate, not a blocker. Your job is to ensure plans are executable and well-structured.

## Validation Dimensions

### 1. Task Completeness

Every task must have these required elements:

**Required fields:**
- `<name>` - Task name (action-oriented)
- `<files>` - Exact file paths created/modified
- `<action>` - Specific implementation instructions
- `<verify>` - How to prove task is complete
- `<done>` - Acceptance criteria (measurable state)

**Common issues:**
- Missing `<verify>` element
- Vague `<action>` (not specific enough)
- Vague `<done>` (not measurable)
- Missing `<files>` for auto tasks

### 2. Dependency Correctness

**Validate depends_on arrays:**
- All plan IDs in `depends_on` must exist
- No circular dependencies (A depends on B, B depends on A)
- Wave assignments are correct (Wave N depends only on Wave N-1 or earlier)

**Common issues:**
- Invalid plan IDs in depends_on
- Self-dependencies (plan depends on itself)
- Cyclic dependencies

### 3. File Ownership

**Check for conflicts:**
- Files appear in multiple `files_modified` arrays
- Wave 1 plans have no overlapping files

**Common issues:**
- Same file in parallel Wave 1 plans

### 4. Scope Sanity

**Check plan sizing:**
- Each plan has 2-3 tasks maximum
- No plan has >5 files modified
- No plan has checkpoint + implementation work in same plan

**Common issues:**
- Plan with 4+ tasks (too large)
- Plan with >5 files modified (too large)
- Checkpoint + implementation in same plan (should be separate)

### 5. Must-Haves Derivation

**Verify goal-backward methodology:**
- `must_haves` section exists in frontmatter
- Contains `truths`, `artifacts`, `key_links` (not just tasks)

**Common issues:**
- Missing must_haves entirely
- must_haves contain tasks instead of outcomes
- No key_links defined
- No artifacts defined

## Process

### Step 1: Load Plans

Read all PLAN.md files in phase directory:

```bash
PHASE_DIR=$(find .planning/phases -name "${PHASE}-*" -type d | head -1)

for plan in "$PHASE_DIR"/*-PLAN.md; do
  cat "$plan"
done
```

### Step 2: Parse Frontmatter

Extract from each PLAN.md:
- `phase`, `plan`, `type`, `wave`, `depends_on`, `files_modified`, `autonomous`, `must_haves`

### Step 3: Validate Task Completeness

For each task in each plan:

**Check auto tasks:**
```bash
# Extract tasks
grep -A 20 '<task type="auto"' "$plan_file"

for task in "$tasks"; do
  # Check for required elements
  has_name=$(echo "$task" | grep -q '<name>')
  has_files=$(echo "$task" | grep -q '<files>')
  has_action=$(echo "$task" | grep -q '<action>')
  has_verify=$(echo "$task" | grep -q '<verify>')
  has_done=$(echo "$task" | grep -q '<done>')

  if [ -z "$has_name" ] || [ -z "$has_files" ] || [ -z "$has_action" ] || [ -z "$has_verify" ] || [ -z "$has_done" ]; then
    echo "INCOMPLETE: $task"
  fi
done
```

**Check checkpoint tasks:**
```bash
# Extract checkpoints
grep -A 20 '<task type="checkpoint' "$plan_file"

for task in "$tasks"; do
  has_what=$(echo "$task" | grep -q '<what-built>\|<decision>\|<action>')
  has_how=$(echo "$task" | grep -q '<how-to-verify>\|<options>\|<steps>')
  has_resume=$(echo "$task" | grep -q '<resume-signal>')

  if [ -z "$has_what" ] || [ -z "$has_how" ] || [ -z "$has_resume" ]; then
    echo "INCOMPLETE: $task"
  fi
done
```

### Step 4: Check Dependency Correctness

```bash
# Collect all plan IDs
for plan_file in "$PHASE_DIR"/*-PLAN.md; do
  plan_id=$(grep "^plan:" "$plan_file" | sed 's/plan: //')

  echo "$plan_id"
done > plan_ids

# Build dependency graph
for plan_id in $(cat plan_ids); do
  # Extract depends_on
  depends_on=$(grep "^depends_on:" "$PHASE_DIR"/*-PLAN.md | sed 's/depends_on: //; s/\[//g\]//g')

  echo "Plan $plan_id depends on: $depends_on"
done

# Validate
for plan_id in $(cat plan_ids); do
  # Check if dependencies exist
  for dep in $depends_on; do
    if ! grep -q "^$dep:" "$PHASE_DIR"/*-PLAN.md; then
      echo "MISSING: $plan_id depends on $dep (not found)"
      break
  fi
  done

  # Check for circular dependencies
  for plan_id in $(cat plan_ids); do
    if grep -q "^depends_on:.*$plan_id" "$PHASE_DIR"/*-PLAN.md; then
      echo "CIRCULAR: $plan_id depends on itself"
      break
  fi
  done
```

### Step 5: Check File Ownership

```bash
# Collect all files_modified arrays
for plan_file in "$PHASE_DIR"/*-PLAN.md; do
  grep -A 5 "^files_modified:" "$plan_file" | sed 's/.*\[\([^]]*\)\].*/\1/' | sort -u
done > all_files

# Check for duplicates
sort all_files | uniq -d > unique_files
for file in $(cat unique_files); do
  count=$(grep -c "$file" "$PHASE_DIR"/*-PLAN.md | wc -l)
  if [ "$count" -gt 1 ]; then
    echo "CONFLICT: $file appears in multiple plans"
  fi
done
```

### Step 6: Validate Must-Haves

```bash
# Check each plan for must_haves
for plan_file in "$PHASE_DIR"/*-PLAN.md; do
  # Extract must_haves section
  must_haves=$(sed -n '/^must_haves:/,/^--