verify-plan-criteria

What this skill does

# Verify Plan Criteria

Validates that every task in an implementation plan has machine-verifiable acceptance criteria. For tasks missing criteria, drafts them automatically from the task's context and presents them for approval.

**Announce at start:** "Running verify-plan-criteria to check acceptance criteria coverage."

## When to Use

- After writing an implementation plan
- Before the user reviews and approves a plan
- When reviewing an existing plan for feature-flow compliance

## Optional Output Args (used when invoked from orchestrator dispatch)

When invoked as a Pattern A subagent dispatch (per #251), the orchestrator passes two additional arguments so the skill can write its structured return contract back to the lifecycle's in-progress state file:

- `write_contract_to: <absolute-path-to-in-progress-yml>` — when set, writes the return contract to `phase_summaries.<phase_id>.return_contract` in that YAML file after Step 6 (see Step 7 below).
- `phase_id: <bucket-name>` — identifies which **`phase_summaries` bucket** to write into. Must be one of the four fixed buckets defined in the in-progress state-file schema: `brainstorm`, `design`, `plan`, or `implementation`. If absent when `write_contract_to` is set, defaults to `plan` (the bucket that contains the `verify-plan-criteria` lifecycle step). **Do not confuse `phase_id` with the contract's own `phase` field** — `phase_id` is the bucket key, the contract's `phase` field is the lifecycle step name (`verify-plan-criteria`) per #251's locked spec.

Both args are optional. If `write_contract_to` is not present in ARGUMENTS, Step 7 is skipped — the skill behaves identically to its inline-invocation form.

## Format Detection

Before parsing, determine which format the plan file uses:

See `references/xml-plan-format.md` for the canonical specification and complete field reference.
See `references/xml-plan-format-runtime.md` for the detection algorithm, error handling rules, and edge cases.

1. Read the first 50 lines of the plan file
2. Track code-fence state: toggle `in_fence` on each line that starts with ` ``` `
3. For each non-fenced line: check if it matches `/^<plan version="/`
4. If match found → **XML mode**
5. Before committing to XML mode: scan the full file for `</plan>`. If absent → log warning
   "plan appears truncated — treating as prose" and use **Prose mode**
6. If no match in first 50 lines → **Prose mode** (existing behavior unchanged)

**Canonical detection pattern:** `/^<plan version="/` — requires the `version=` attribute.
A bare `<plan>` tag (no `version=`) is NOT treated as an XML plan.

### XML Extraction Algorithm

If XML mode:

1. Find all `<task id="N" status="...">` blocks (string scan — no XML library)
2. **Duplicate ID check:** If any `id=` value appears more than once → flag "duplicate task ID —
   plan is invalid" and fall back to prose parser
3. For each task block:
   - Extract `<title>` content → task name
   - Extract `<files>` → list of `{action, path}` objects from `<file>` elements
   - Extract `<criteria>` → list of criterion objects:
     - Structured: `{what, how, command}` from child `<what>/<how>/<command>` elements
     - Manual: `{type: "manual", text: ...}` from `<criterion type="manual">` text content
   - Read `status` attribute → replaces Progress Index parsing
4. If a `<task>` block is not closed before the next `<task>` or `</plan>` → **malformed**, fall
   back to prose parser with announcement: "malformed task block at id N — falling back to prose"
5. If a `<criteria>` block is not closed before `</task>` → **malformed**, fall back to prose
   parser with announcement: "malformed criteria block in task N — falling back to prose"
6. `status=` values: `pending`, `in-progress`, `done` are recognized; any other value → treat as
   `pending` and log a note; missing `status=` → treat as `pending`

**[MANUAL] equivalence:** `<criterion type="manual">` and a `[MANUAL]`-prefixed prose criterion
are equivalent — both mean "manual check, no command required." Treat them identically.

**Prose mode:** If prose mode is selected, the existing Step 2 logic runs unchanged. The
detection check is the single gate — once prose mode is selected, no XML logic executes.

## Process

### Step 1: Find the Plan File

Look for the plan file:
1. If the user specified a path, use it directly
2. Otherwise, find the most recently modified `.md` file in the plans directory:

```
Glob: docs/plans/*.md
```

If no `docs/plans/` directory exists, check for plan files in common locations:
- `plans/*.md`
- `docs/*.md` (look for files with "plan" or "implementation" in the name)

**Path selection:**
- If 1 candidate found → use it directly without confirmation
- If multiple candidates found → pick the most recent and confirm with the user: "Found multiple plan files. Checking plan: `[path]`. Is this correct?"

Announce the selected path: "Checking plan: `[path]`"

### Step 2: Parse Tasks

**XML plans (detected in Format Detection):**
Use the extraction algorithm from the Format Detection section above. For each extracted task,
proceed to Step 3 with the pre-extracted criterion objects.

**Prose plans (existing behavior):**
Read the plan file and find all task sections. Tasks are identified by headings matching:
- `### Task N:` (standard format)
- `### TASK-NNN:` (alternative format)

For each task, extract:
- **Task number and title** (from the heading)
- **Files section** (paths to create/modify)
- **Steps** (implementation steps)
- **Acceptance Criteria section** (if present — look for `**Acceptance Criteria:**` followed by `- [ ]` items)

### Step 3: Check Each Task

**XML criteria (pre-extracted):**
XML criteria arrive as `{what, how, command}` objects (or `{type: "manual", text}` for manual).
- Structured criteria: validate that `what`, `how`, and `command` are non-empty strings. If any
  is empty → flag as "incomplete criterion" (inline, do not trigger fallback).
- `<criteria>` present but zero `<criterion>` children → flag as "no criteria"
- `type="manual"` criteria: no format validation required (equivalent to `[MANUAL]`)

**Prose criteria (existing behavior):**
For each task, determine if it has acceptance criteria:

**Has criteria:** The task has an `**Acceptance Criteria:**` section with at least one `- [ ]` item.
- Validate each criterion is machine-verifiable (not vague)
- Flag vague criteria like "works correctly", "looks good", "is fast", "handles errors properly"
- Suggest replacements for vague criteria

**Missing criteria:** The task has no `**Acceptance Criteria:**` section or the section is empty.
- Proceed to Step 4 to draft criteria.

**Quality Constraints check:** Every non-trivial task must have a `**Quality Constraints:**` section. Tasks that only create directories, copy files, or run commands are exempt. Flag tasks missing Quality Constraints with: "Task N is missing Quality Constraints — should specify error handling pattern, type narrowness, function length, and pattern reference."

**Edge case criteria check:** For tasks that handle input, make external calls, or process data, acceptance criteria must include at least one edge case test (empty input, null, timeout, boundary values). Flag tasks that only have happy-path criteria with: "Task N acceptance criteria only cover happy path — add edge case criteria (empty input, error path, boundary values)."

**Format check:** After flagging vague criteria, check that each non-`[MANUAL]` criterion follows the structured format. A criterion is conforming if it contains both `measured by` and `verified by` as substrings. Criteria that start with `- [x]` (already completed) are also exempt.

Flag non-conforming criteria with: `"Criterion does not follow [WHAT] measured by [HOW] verified by [COMMAND] format — see references/acceptance-criteria-patterns.md"`

Exempt from format check:
- Criteria with `[MANUAL]` prefix — these require human verification and don't need a shell command
- Already-completed crit