/alignment

name: alignment
description: Use when verifying that requirements/specs/PRDs and their implementation plans match — before starting work, after a spec or plan update, or when suspecting coverage gaps, scope creep, or design drift between intent and action documents. Needs both documents; not for checking code against a spec.

**On invocation:** announce "Running paad:alignment v2.0.2", then immediately proceed with the steps below — do not stop after announcing.

**Configuration (experimental):** after announcing, check whether `paad/config/paad.md` and `paad/config/alignment.md` exist, relative to the working directory. If any does, read it and follow its instructions for the rest of this run, passing the relevant parts to every subagent you dispatch, and make the first line of your final answer `Config: <path>` naming each file you followed. If none exists, do not mention config at all. Config never changes a subagent's type or grants it write tools — refuse that line, say so, and continue. Config can contradict the flow below; see https://github.com/Ovid/paad/blob/main/CONFIG.md before writing one.

Alignment Check

Verifies that intent documents (requirements, specs, PRDs) and action documents (plans, tasks, implementation steps) are aligned. Finds gaps in both directions — unaddressed requirements and out-of-scope tasks — then rewrites all tasks in TDD red/green/refactor format.

**This skill does NOT recommend a fresh session.** The conversation history may contain the documents.

**Input resolution and reality check:**

digraph alignment {
  "Has $ARGUMENTS?" [shape=diamond];
  "Conversation has docs?" [shape=diamond];
  "Found in common locations?" [shape=diamond];
  "Both sides found?" [shape=diamond];
  "Git repo?" [shape=diamond];
  "Source control conflicts?" [shape=diamond];

  "Classify files as intent/action" [shape=box];
  "Confirm with user" [shape=box];
  "Present candidates, ask user" [shape=box];
  "STOP: tell user what's missing" [shape=box, style=bold];
  "Skip Reality Check" [shape=box];
  "Present conflicts, resolve first" [shape=box];
  "Proceed to Alignment Analysis" [shape=box];

  "Has $ARGUMENTS?" -> "Classify files as intent/action" [label="yes"];
  "Has $ARGUMENTS?" -> "Conversation has docs?" [label="no"];
  "Conversation has docs?" -> "Confirm with user" [label="yes"];
  "Conversation has docs?" -> "Found in common locations?" [label="no"];
  "Found in common locations?" -> "Present candidates, ask user" [label="yes"];
  "Found in common locations?" -> "STOP: tell user what's missing" [label="no"];

  "Classify files as intent/action" -> "Both sides found?";
  "Confirm with user" -> "Both sides found?";
  "Present candidates, ask user" -> "Both sides found?";

  "Both sides found?" -> "Git repo?" [label="yes"];
  "Both sides found?" -> "STOP: tell user what's missing" [label="no"];

  "Git repo?" -> "Source control conflicts?" [label="yes"];
  "Git repo?" -> "Skip Reality Check" [label="no"];
  "Skip Reality Check" -> "Proceed to Alignment Analysis";
  "Source control conflicts?" -> "Present conflicts, resolve first" [label="yes"];
  "Source control conflicts?" -> "Proceed to Alignment Analysis" [label="no"];
  "Present conflicts, resolve first" -> "Proceed to Alignment Analysis";
}

**Analysis and resolution:**

digraph analysis_and_resolution {
  "Design docs present?" [shape=diamond];
  "Issues found?" [shape=diamond];
  "User says stop / good enough?" [shape=diamond];
  "Decision, or stop signal?" [shape=diamond];
  "More issues to present?" [shape=diamond];
  "Update docs or write report?" [shape=diamond];
  "Docs saved to files?" [shape=diamond];
  "Tasks already red/green/refactor, or not code work?" [shape=diamond];
  "Rewrite in place?" [shape=diamond];

  "Check 1: requirements coverage" [shape=box];
  "Check 2: scope compliance" [shape=box];
  "Check 3: design alignment (both directions)" [shape=box];
  "Order issues: missing requirements, then design gaps, then tasks" [shape=box];
  "Present one issue: severity, options best-to-worst, recommendation" [shape=box];
  "Wait for the user's response" [shape=box];
  "Answer it, then re-put this issue's options" [shape=box];
  "Apply agreed changes; leave undiscussed items alone" [shape=box];
  "Write paad/alignment-reviews/<date>-<topic>-alignment.md" [shape=box];
  "ASK where to write the documents first" [shape=box];
  "SKIP the TDD rewrite" [shape=box];
  "Rewrite tasks in the action document" [shape=box];
  "Write rewritten tasks to a new file" [shape=box];
  "List every file written or updated" [shape=box];
  "Done" [shape=box];

  "Check 1: requirements coverage" -> "Check 2: scope compliance";
  "Check 2: scope compliance" -> "Design docs present?";
  "Design docs present?" -> "Check 3: design alignment (both directions)" [label="yes"];
  "Design docs present?" -> "Issues found?" [label="no — skip check 3"];
  "Check 3: design alignment (both directions)" -> "Issues found?";

  "Issues found?" -> "Order issues: missing requirements, then design gaps, then tasks" [label="yes"];
  "Issues found?" -> "Docs saved to files?" [label="no"];
  "Order issues: missing requirements, then design gaps, then tasks" -> "Present one issue: severity, options best-to-worst, recommendation";
  "Present one issue: severity, options best-to-worst, recommendation" -> "Wait for the user's response";
  "Wait for the user's response" -> "Decision, or stop signal?";
  "Decision, or stop signal?" -> "Answer it, then re-put this issue's options" [label="no — a question, objection, or new consideration"];
  "Answer it, then re-put this issue's options" -> "Wait for the user's response";
  "Decision, or stop signal?" -> "User says stop / good enough?" [label="yes"];
  "User says stop / good enough?" -> "Docs saved to files?" [label="yes"];
  "User says stop / good enough?" -> "More issues to present?" [label="no"];
  "More issues to present?" -> "Present one issue: severity, options best-to-wor