/alignment-check

Alignment Check

**Before reading further, print this status line so the user sees a progress signal during the upcoming reasoning pass:**

> *Working through the alignment loop - investigating where this story fits in the codebase, can take 30-90 seconds...*

You are running the codebase alignment check for a story. This is the engineer-to-product-manager handshake - you spawn an Explore agent to investigate the codebase where this work will land, and surface every product question that only the user can answer.

Definition: 95% Alignment

**95% alignment means: "I have asked the user every question the codebase raised that only they can answer."**

It is NOT about:

• Whether the solution approach is right (that's your job as the engineer)
• Whether the chunks will work (that's plan-chunks' job)
• Whether the code will compile (that's validation's job)

It IS about:

• **Conflicts discovered** - "Found existing X - replace, update, or coexist?" → asked
• **Adjacencies & suggestions** - "This pattern exists in N other places - apply there too?" → asked
• **Assumptions surfaced** - "You said X but the codebase implies Y - which is it?" → asked
• **Scope implications confirmed** - "Your answers expanded this - split or keep?" → asked

**The gate is not "do I feel confident?" It's "do I have zero unasked product questions?"**

Product questions go to the user. Engineering questions you solve yourself. The gate measures whether the user's intent is fully captured - not whether you know how to build it.

When This Runs

• During `craft-story-new` Step 8 (when user chose "Keep designing", before acceptance criteria)
• During `craft-cycle-design` per-story (before plan-chunks)
• During `plan-chunks` Phase 0 (if `alignment: pending` in story frontmatter - catches stories that skipped the check during creation)

Prerequisites

Before starting, you need: 1. The story file path (to read the spark, decisions, scope) 2. The story's `## Likely Files` section (if it exists - gives a starting point for investigation) 3. Any decisions captured so far

The Loop

Step 0: Empty-Codebase Short-Circuit

Before spawning the Explore agent, check whether the codebase has any source files. An empty codebase has zero adjacencies to find — running Explore would burn time and tokens to confirm there's nothing to find.

**Check (rough):** Look for any files outside `.craft/`, `.claude/`, `node_modules/`, `.git/`, and root-level dotfiles. Bash one-liner option:

find . -type f \
  -not -path './.craft/*' \
  -not -path './.claude/*' \
  -not -path './node_modules/*' \
  -not -path './.git/*' \
  -not -name '.*' \
  | head -1

If the result is empty: **skip Step 1 entirely.** There's no codebase to investigate.

**Where product questions come from on an empty codebase:**

Read the story's `## Notes` section (populated during cycle-design Phase 2a's brainstorm). Open questions raised during the brainstorm — naming choices, scope questions, data shape decisions — are the natural source of product questions for greenfield work.

After harvesting questions from the Notes section, **skip ahead to Step 3 (Surface Gaps via AskUserQuestion)** to surface them to the user.

If the codebase has any source files: continue to Step 0.5 as normal.

Step 0.5: Planning Context Injection (Planning-Sourced Stories Only)

Before spawning the Explore agent, check whether this story was created from a planning concept. If so, build a Planning Context block from the story's Reference Materials so the agent doesn't surface false-positive product questions for decisions already captured in planning.

**Detection:** Read the story frontmatter. If `source_concept:` is populated, this is a planning-sourced story - continue with the injection. If not, skip directly to Step 1 with the existing prompt unchanged.

**Build the Planning Context block (orchestrator-level work, NOT delegated to the Explore agent):**

1. Read the story's `## Reference Materials` section.

2. Parse each citation: extract the file path + anchor(s). Citations may have multiple anchors per file (multi-anchor format - see plan-chunks-agent.md section 1.3.5 for the contract).

3. For each cited file + anchor, use **Read** with the anchor to extract the excerpt. Apply the same anchor-aware reading rules from plan-chunks-agent's Reference Materials contract:

• Planning files: locate `## Section` + `### Subheading` / `Decision #N` / dated entry, read that section only
• Mockups: read the cited line range or HTML id
• locked.md: read Pattern N's section
• tokens.yaml: look up the token name
• active.md: read the dated entry within `## Recent state changes`
• Code files: read the cited function/class or line range

4. **Stale-anchor handling during injection (MANDATORY):** If a cited anchor cannot be resolved (section heading no longer exists, line range out of bounds, Pattern N missing from locked.md), do NOT silently omit. Surface the stale anchor BEFORE spawning the Explore agent via **AskUserQuestion**:

   question: "Reference Materials cites '[file path] -> [anchor]' but the anchor doesn't resolve in the current file. The story may have been written against an older version. How should we proceed?"
   header: "Stale Anchor"
   options:
     - label: "Skip this citation"
       description: "Proceed with alignment-check using the resolved citations only. This citation's content won't reach the agent."
     - label: "Re-extract from current planning"
       description: "Restart story creation flow (re-run /craft:story-new From planning) to refresh citations - alignment-check will run afterward."
     - label: "Provide replacement anchor"
       description: "Type the correct section/subheading/range manually."

"Skip" -> proceed without that excerpt; "Re-extract" -> exit alignment-check with instruction to re-run story-from-planning; "Provide replacement anchor" -> capture user's input, retry the Read, continue