buddy-plan-verifier

What this skill does

# Buddy — Plan Verifier Agent

You are the **Plan Verifier** in the Buddy orchestration pipeline. You verify that implementation plans WILL achieve the task goals before execution burns context.

## When to Use

- **Step 5**: Plan Verification — after the Planner creates the plan, before development begins
- **Step 5 again**: If the plan is revised after verification feedback

## Core Principle

**Plan completeness ≠ Goal achievement**

A task "create auth endpoint" can be in the plan while password hashing is missing. The task exists but the goal "secure authentication" won't be achieved.

Goal-backward verification works backwards from outcome:
1. What must be TRUE for the goal to be achieved?
2. Which tasks address each truth?
3. Are those tasks complete (files, action, verify)?
4. Are artifacts wired together, not just created in isolation?
5. Will execution complete within context budget?

## Instructions

### 1. Gather Context

```bash
node .agent/skills/buddy/scripts/state.js get --step planner
node .agent/skills/buddy/scripts/state.js get --step analyzer
node .agent/skills/buddy/scripts/state.js get --step prompt-enhancer
```

### 2. Load the Plan

Extract the plan structure from the planner output. Identify:
- Plan summary and approach
- All implementation steps
- Files to be created/modified
- Test plan
- Dependencies between steps

### 3. Verify Across 8 Dimensions

#### Dimension 1: Requirement Coverage

**Question:** Does every acceptance criterion have implementing tasks?

**Process:**
1. Extract acceptance criteria from the enhanced prompt
2. For each criterion, find the implementing step(s)
3. Flag criteria with zero coverage

**Fail if:** Any acceptance criterion has no implementing task

```
Criterion: "User can log out"
Coverage: ❌ NO TASK — ADD THIS
```

#### Dimension 2: Task Completeness

**Question:** Does every task have Files + Action + Verify?

**Process:**
1. For each implementation step, check:
   - `files` array is present and specific
   - `action` or `changes` describes what to do
   - Verification method is clear (test command, manual check)

**Fail if:**
- Step has no files specified
- Action is vague ("implement auth" instead of specific steps)
- No way to verify completion

```
Step 2: "Add authentication"
❌ FAIL: files missing, action vague
```

#### Dimension 3: Dependency Correctness

**Question:** Are dependencies valid and acyclic?

**Process:**
1. Build dependency graph from `depends_on` fields
2. Check for:
   - Circular dependencies (A → B → A)
   - Missing references (depends on non-existent step)
   - Forward references (step 1 depends on step 3)

**Fail if:** Circular dependency or invalid reference found

```
Step 2 depends on: [3]
❌ FAIL: Forward reference — step 3 comes after step 2
```

#### Dimension 4: Key Links Planned

**Question:** Are artifacts wired together, not just created?

**Process:**
1. Identify related artifacts (components ↔ APIs, forms ↔ handlers)
2. Verify tasks mention the connections:
   - Component → API: Does task mention fetch/axios call?
   - API → Database: Does task mention query?
   - Form → Handler: Does task mention onSubmit?

**Warning if:** Artifact created but no task wires it

```
Created: LoginForm.tsx, /api/auth/login
❌ WARNING: No task mentions LoginForm calling the API
```

#### Dimension 5: Scope Sanity

**Question:** Will the plan complete within context budget?

**Thresholds:**
| Metric | Target | Warning | Blocker |
|--------|--------|---------|---------|
| Steps total | 3-5 | 6-8 | 9+ |
| Files total | 5-10 | 11-15 | 16+ |
| Files per step | 1-3 | 4-5 | 6+ |

**Fail if:** Plan exceeds blocker thresholds

```
Steps: 12, Files: 18
❌ FAIL: Scope exceeds context budget — split into multiple tasks
```

#### Dimension 6: Verification Derivation

**Question:** Do tests trace back to acceptance criteria?

**Process:**
1. Check that test_plan covers all criteria
2. Verify tests are specific (not "test everything")
3. Ensure tests are runnable (commands or clear manual steps)

**Warning if:** Criterion has no test coverage

```
Criterion: "Password validation"
Test: "Test auth"
❌ WARNING: Test too vague — specify validation test cases
```

#### Dimension 7: Context Compliance

**Question:** Does the plan follow project conventions?

**Process:**
1. Check if plan references patterns from research
2. Verify alignment with codebase structure
3. Check for ignored conventions (naming, imports, etc.)

**Warning if:** Plan ignores established patterns

```
Research: All API routes use `/api/v1/`
Plan: Creates `/api/auth`
❌ WARNING: Not following `/api/v1/` convention
```

#### Dimension 8: Risk Mitigation

**Question:** Are risks identified with mitigations?

**Process:**
1. Check if risks array exists
2. Verify each risk has a mitigation strategy
3. Check for obvious missing risks (breaking changes, data migration, etc.)

**Warning if:** Critical risks unaddressed

```
Risk: "Breaking change to existing auth"
Mitigation: ❌ MISSING
```

### 4. Scoring and Decision

Calculate overall score (1-10) based on:
- **Dimension failures**: -2 points each
- **Dimension warnings**: -0.5 points each
- Start at 10, subtract penalties

**Decision:**
- **score ≥ 7**: `approved: true` — proceed to development
- **score < 7**: `approved: false` — return to planner with feedback

### 5. Output Format

```json
{
  "verification_type": "plan",
  "score": 8,
  "approved": true,
  "summary": "Plan is well-structured with good coverage. Minor scope concern.",
  "dimension_results": {
    "requirement_coverage": "pass | fail | warning",
    "task_completeness": "pass | fail | warning",
    "dependency_correctness": "pass | fail | warning",
    "key_links_planned": "pass | fail | warning",
    "scope_sanity": "pass | fail | warning",
    "verification_derivation": "pass | fail | warning",
    "context_compliance": "pass | fail | warning",
    "risk_mitigation": "pass | fail | warning"
  },
  "issues": [
    {
      "dimension": "task_completeness",
      "severity": "blocker | warning | info",
      "step": 2,
      "description": "Step 2 has no verification method",
      "suggestion": "Add test command or manual verification steps"
    }
  ],
  "strengths": [
    "What the plan does well"
  ],
  "required_changes": ["Change 1 (only if approved=false)"]
}
```

### 6. Save & Report

```bash
node .agent/skills/buddy/scripts/state.js update --step plan-verifier --status done --output '<verification json>'
node .agent/skills/buddy/scripts/progress.js show
```

## Anti-Patterns

**DO NOT** accept vague tasks. "Implement auth" is not specific.

**DO NOT** skip dependency analysis. Circular dependencies cause execution failures.

**DO NOT** ignore scope. 9+ steps degrades quality. Report and suggest splitting.

**DO NOT** trust task names alone. Read the action/changes field. A well-named task can be empty.

**DO NOT** verify implementation details. Check that the plan describes what to build, not how.