validate

<context>
Workflow Detection: Auto-detected via workspace files, branch pattern, or state.yaml

Current workflow state: Auto-detected from ${BASE_DIR}/\*/state.yaml

Feature spec exists: Auto-detected (epics/_/epic-spec.md OR specs/_/spec.md)

Plan exists: Auto-detected (epics/_/plan.md OR specs/_/plan.md)

Tasks exist: Auto-detected (epics/_/tasks.md OR specs/_/tasks.md)

Engineering Principles: !`test -f docs/project/engineering-principles.md && echo "✅ Found" || echo "❌ Missing (run /init-project)"`

Previous validation: Auto-detected from ${BASE_DIR}/\*/analysis-report.md
</context>

<objective>
Cross-artifact consistency analysis to validate implementation readiness.

**Analyzes:**

- Spec ↔ Plan ↔ Tasks consistency
- Constitution compliance (8 engineering principles)
- Breaking changes (API, schema, env vars)
- Test coverage completeness
- Implementation readiness

**Outputs:**

- analysis-report.md with CRITICAL/MAJOR/MINOR findings
- Recommendation: PROCEED | FIX_CRITICAL | FIX_ALL

**Operating constraints:**

- **STRICTLY READ-ONLY** — Never modify spec, plan, or tasks files
- **Constitution Authority** — Constitution violations auto-CRITICAL
- **Token Efficient** — Max 50 findings, aggregate overflow
- **Deterministic** — Consistent finding IDs across runs

**Dependencies:**

- Git repository initialized
- spec.md, plan.md, tasks.md completed
- Optional: docs/project/engineering-principles.md for principle validation
  </objective>

<process>

### Step 0: WORKFLOW DETECTION

**Detect workflow using centralized skill** (see `.claude/skills/workflow-detection/SKILL.md`):

1. Run detection: `bash .spec-flow/scripts/utils/detect-workflow-paths.sh`
2. Parse JSON: Extract `type`, `base_dir`, `slug` from output
3. If detection fails (exit code != 0): Use AskUserQuestion fallback
4. Set paths:
   - Feature: `SPEC_FILE="${BASE_DIR}/${SLUG}/spec.md"`
   - Epic: `SPEC_FILE="${BASE_DIR}/${SLUG}/epic-spec.md"`
   - Common: `PLAN_FILE`, `TASKS_FILE`, `REPORT_FILE` all in `${BASE_DIR}/${SLUG}/`

**Fallback prompt** (if detection fails):
- Question: "Which workflow are you working on?"
- Options: "Feature" (specs/), "Epic" (epics/)

---

### Step 1: Execute Validation Workflow

1. **Execute the validation workflow process in this command**. In this checkout,
   direct `spec-cli.py validate` is only a compatibility preflight shim:

   ```bash
   python .spec-flow/scripts/spec-cli.py validate "$ARGUMENTS"
   ```

   The installed workflow command performs:
   a. **Prerequisite validation** — Runs check-prerequisites.sh with --require-tasks flag
   b. **Load artifacts** — Reads spec.md, plan.md, tasks.md, engineering-principles.md
   c. **Run 6 detection passes**:

   - Pass 1: Constitution violations (auto-CRITICAL)
   - Pass 2: Spec ↔ Plan consistency
   - Pass 3: Plan ↔ Tasks consistency
   - Pass 4: Breaking changes (API, schema, env vars)
   - Pass 5: Test coverage analysis
   - Pass 6: Implementation readiness
     d. **Assign severity** — CRITICAL/MAJOR/MINOR based on implementation impact
     e. **Generate report** — Creates analysis-report.md with findings and remediation
     f. **Git commit** — Commits validation report
     g. **Suggest next** — Recommends /implement or fix blockers

2. **Read generated report**:

   - Load `$REPORT_FILE` (created by script, path: `${BASE_DIR}/*/analysis-report.md`)
   - Review executive summary with severity counts
   - Examine findings grouped by severity (CRITICAL → MAJOR → MINOR)

3. **Assess severity distribution**:

   **CRITICAL (Blocks implementation):**

   - Constitution violations
   - Spec-plan contradictions (different tech stack, incompatible requirements)
   - Missing external dependencies (APIs, services not provisioned)
   - Breaking changes without migration plan

   **MAJOR (Causes rework):**

   - Plan-tasks misalignment (tasks don't implement plan sections)
   - Incomplete test coverage (acceptance criteria without tests)
   - Unclear implementation details (authentication flow ambiguous)

   **MINOR (Nice to fix):**

   - Cosmetic inconsistencies (different terminology for same concept)
   - Optional test coverage (edge cases for rare scenarios)
   - Documentation gaps (missing inline comments, README updates)

   **Decision logic:**

   ```
   IF critical_findings > 0 THEN
     recommendation = FIX_CRITICAL
   ELSE IF major_findings > 5 THEN
     recommendation = FIX_ALL
   ELSE
     recommendation = PROCEED
   END IF
   ```

4. **Present results to user**:

   **Summary format:**

   ```
   Validation Summary

   Feature: {slug}
   Artifacts analyzed: spec.md, plan.md, tasks.md, engineering-principles.md

   Findings:
     CRITICAL: {count} (blocks implementation)
     MAJOR: {count} (causes rework)
     MINOR: {count} (nice to fix)

   Constitution compliance: {PASS|FAIL}

   Top issues:
     1. [CRITICAL-001] {Title} - {Impact}
     2. [CRITICAL-002] {Title} - {Impact}
     3. [MAJOR-001] {Title} - {Impact}

   Recommendation: {PROCEED|FIX_CRITICAL|FIX_ALL}
   ```

5. **Suggest next action** based on recommendation:

   **PROCEED (No blockers):**

   ```
   ✅ No critical issues found. Ready for implementation.

   Next: /implement

   All artifacts are consistent. {minor_count} minor findings can be addressed during implementation.
   ```

   **FIX_CRITICAL ({count} blockers):**

   ```
   ❌ {count} critical findings block implementation

   Blockers:
     {List CRITICAL findings with remediation}

   Fix these issues first, then re-run /validate to verify.
   ```

   **FIX_ALL (Too many major issues):**

   ```
   ⚠️  {major_count} major issues will cause implementation rework

   Recommendation: Fix major issues before /implement to avoid costly rework.

   Options:
     A) Fix all major issues now (recommended)
     B) Proceed anyway (risk: 30-40% rework during implementation)
   ```

   </process>

<verification>
Before completing, verify:
- analysis-report.md created in ${BASE_DIR}/*/
- Report contains all 6 detection