Validation Gates¶

Purpose: Phase transition requirements and enforcement mechanisms to prevent incomplete work
Status: ACTIVE
Version: 1.0.0
Last Updated: 2025-12-19

🚦 Overview¶

Purpose: Prevent phase progression with incomplete work. Each phase MUST pass validation before the next phase can begin.

Responsibility: @workflow-manager enforces all validation gates.

Gate 1: CAPTURE → OBSERVE¶

Prerequisites - Artifacts¶

✅ idea.md exists and contains problem/opportunity description
✅ version.json created with workflow stage = "captured"

Prerequisites - Validation¶

✅ capture/validation/capture-validation.md exists and shows PASSED status (score ≥6/10)
✅ capture/validation/capture-to-observe-gate.md created with decision

Prerequisites - Memory¶

✅ Step memories: 6 files in capture/memory/ named step-1.md through step-6.md
✅ Phase summary: capture/memory/capture-phase-summary.md exists (≤250 tokens)

Validation Command¶

# Artifact check
test -f idea.md && test -f version.json

# Validation check
test -f capture/validation/capture-validation.md

# Memory count
ls capture/memory/step-*.md 2>/dev/null | wc -l
# Expected: 6

# Token budget check (approximate: 1 token ≈ 0.75 words)
wc -w < capture/memory/capture-phase-summary.md
# Expected: ≤188 words (≈250 tokens)

Block Condition: If idea.md missing OR validation failed OR step memory count ≠ 6 OR phase summary missing OR token budget exceeded

Gate 2: OBSERVE → ORIENT¶

Prerequisites - Artifacts¶

✅ observe/artifacts/initial-jtbd-frame.md exists
✅ Minimum 3 executor interviews present (or 6 if all Six Hats used)
Files: observe/artifacts/interviews/executors/blue-hat-*.md, white-hat-*.md, green-hat-*.md
✅ Minimum 3 beneficiary interviews present
Files: observe/artifacts/interviews/beneficiaries/*.md (count ≥ 3)
✅ observe/artifacts/job-definition.md exists
✅ observe/artifacts/job-journey.md exists
✅ observe/artifacts/outcome-gaps.md exists

Prerequisites - Validation¶

✅ observe/validation/observe-validation.md exists and shows PASSED status (score ≥8/10)
✅ observe/validation/observe-advisory-review.md exists with alignment score ≥8/10
✅ observe/validation/observe-to-orient-gate.md created with decision

Prerequisites - Memory¶

✅ Step memories: 8 files in observe/memory/ named step-1.md through step-8.md (150-250 tokens each)
✅ Phase summary: observe/memory/observe-phase-summary.md exists (≤900 tokens)

Validation Command¶

# Artifact count check
ls observe/artifacts/initial-jtbd-frame.md observe/artifacts/job-definition.md observe/artifacts/job-journey.md observe/artifacts/outcome-gaps.md observe/artifacts/observe-validation.md 2>/dev/null | wc -l
# Expected: 5

# Executor interview count
ls observe/artifacts/interviews/executors/*.md 2>/dev/null | wc -l
# Expected: 3 (Option 3B/3C) or 6 (Option 3A)

# Memory count
ls observe/memory/step-*.md 2>/dev/null | wc -l
# Expected: 8

Block Condition: If any artifact missing OR step memory count ≠ 8 OR validation not passed

Prerequisites - Artifacts¶

✅ orient/artifacts/symptoms-analysis.md exists
✅ orient/artifacts/diagnosis.md exists
✅ orient/artifacts/prognosis.md exists
✅ orient/artifacts/problem-statement.md exists
✅ orient/artifacts/kano-classification.md exists
✅ orient/artifacts/rice-prioritization.md exists
✅ orient/artifacts/problem-prioritization.md exists

Prerequisites - Validation¶

✅ orient/validation/orient-validation.md exists and shows PASSED status (score ≥8/10)
✅ orient/validation/orient-advisory-review.md exists with alignment score ≥8/10
✅ orient/validation/orient-to-recommend-gate.md created with decision

Prerequisites - Memory¶

✅ Step memories: 11 files in orient/memory/ named step-1.md through step-11.md (150-250 tokens each)
Note: Includes separate steps for Kano (step-5), RICE (step-6), Combined Prioritization (step-7), and conditional Revision (step-8)
✅ Phase summary: orient/memory/orient-phase-summary.md exists (≤900 tokens)

Validation Command¶

# Artifact count check (all 8 required files)
ls orient/artifacts/symptoms-analysis.md orient/artifacts/diagnosis.md orient/artifacts/prognosis.md orient/artifacts/problem-statement.md orient/artifacts/kano-classification.md orient/artifacts/rice-prioritization.md orient/artifacts/problem-prioritization.md orient/artifacts/orient-validation.md 2>/dev/null | wc -l
# Expected: 8

# Memory count
ls orient/memory/step-*.md 2>/dev/null | wc -l
# Expected: 11

Content Compliance Checks (REQUIRED)¶

Kano Classification:

# Check kano-classification.md contains all 4 categories
grep -q "Must-Be" orient/artifacts/kano-classification.md && \
grep -q "Performance" orient/artifacts/kano-classification.md && \
grep -q "Attractive" orient/artifacts/kano-classification.md && \
grep -q "Indifferent" orient/artifacts/kano-classification.md
# Expected: All 4 patterns found (exit code 0)

RICE Prioritization:

# Check rice-prioritization.md contains RICE formula
grep -q "Reach.*Impact.*Confidence.*Effort" orient/artifacts/rice-prioritization.md && \
grep -q "RICE Score" orient/artifacts/rice-prioritization.md
# Expected: Both patterns found (exit code 0)

Combined Prioritization:

# Check problem-prioritization.md references BOTH frameworks
grep -q "Kano" orient/artifacts/problem-prioritization.md && \
grep -q "RICE" orient/artifacts/problem-prioritization.md && \
grep -q "P0" orient/artifacts/problem-prioritization.md
# Expected: All 3 patterns found (exit code 0)

Validation Metadata:

# Check orient-validation.md shows frameworks applied
grep -q '"kano_applied": true' orient/artifacts/orient-validation.md && \
grep -q '"rice_applied": true' orient/artifacts/orient-validation.md && \
grep -q '"validation_status": "pass"' orient/artifacts/orient-validation.md
# Expected: All 3 patterns found (exit code 0)

Block Condition: If any artifact missing OR step memory count ≠ 11 OR validation score <8/10 OR advisory score <8/10 OR any content check fails

Critical: This gate would have prevented V1's 63% Recommend phase score by blocking transition.

Prerequisites - Artifacts¶

✅ recommend/artifacts/solution-hypotheses.md exists
✅ recommend/artifacts/blue-ocean-analysis.md exists (exact name, not variants)
✅ recommend/artifacts/solution-rice.md exists (exact name, not variants)
✅ recommend/artifacts/solution-prioritization.md exists
✅ recommend/artifacts/recommendation-selection.md exists
✅ recommend/artifacts/recommendation.md exists

Prerequisites - Validation¶

✅ recommend/validation/recommend-validation.md exists and shows PASSED status (score ≥8/10)
✅ recommend/validation/recommend-advisory-review.md exists with alignment score ≥8/10
✅ recommend/validation/recommend-to-align-gate.md created with decision

Prerequisites - Memory¶

✅ Step memories: 8 files in recommend/memory/ named step-1.md through step-8.md (150-250 tokens each)
✅ Phase summary: recommend/memory/recommend-phase-summary.md exists (≤900 tokens)

Validation Command¶

# Artifact count check (all 7 required files)
ls recommend/artifacts/solution-hypotheses.md recommend/artifacts/blue-ocean-analysis.md recommend/artifacts/solution-rice.md recommend/artifacts/solution-prioritization.md recommend/artifacts/recommendation-selection.md recommend/artifacts/recommendation.md recommend/artifacts/recommend-validation.md 2>/dev/null | wc -l
# Expected: 7

# Memory count
ls recommend/memory/step-*.md 2>/dev/null | wc -l
# Expected: 8

Content Compliance Checks (REQUIRED)¶

Blue Ocean Analysis:

# Check blue-ocean-analysis.md contains ERRC grid
grep -q "Eliminate" recommend/artifacts/blue-ocean-analysis.md && \
grep -q "Reduce" recommend/artifacts/blue-ocean-analysis.md && \
grep -q "Raise" recommend/artifacts/blue-ocean-analysis.md && \
grep -q "Create" recommend/artifacts/blue-ocean-analysis.md
# Expected: All 4 ERRC actions found (exit code 0)

RICE Prioritization for Solutions:

# Check solution-rice.md contains RICE formula and scores
grep -q "Reach.*Impact.*Confidence.*Effort" recommend/artifacts/solution-rice.md && \
grep -q "RICE Score" recommend/artifacts/solution-rice.md
# Expected: Both patterns found (exit code 0)

Combined Prioritization:

# Check solution-prioritization.md combines Blue Ocean + RICE
grep -q "Blue Ocean" recommend/artifacts/solution-prioritization.md && \
grep -q "RICE" recommend/artifacts/solution-prioritization.md && \
grep -q "Tier" recommend/artifacts/solution-prioritization.md
# Expected: All 3 patterns found (exit code 0)

SCAMPER Application:

# Check solution-hypotheses.md uses SCAMPER
grep -E -q "Substitute|Combine|Adapt|Modify|Put to other use|Eliminate|Reverse" recommend/artifacts/solution-hypotheses.md
# Expected: At least one SCAMPER technique found (exit code 0)

Validation Metadata:

# Check recommend-validation.md shows frameworks applied
grep -q '"blue_ocean_applied": true' recommend/artifacts/recommend-validation.md && \
grep -q '"rice_applied": true' recommend/artifacts/recommend-validation.md && \
grep -q '"scamper_applied": true' recommend/artifacts/recommend-validation.md && \
grep -q '"validation_status": "pass"' recommend/artifacts/recommend-validation.md
# Expected: All 4 patterns found (exit code 0)

Block Condition: If any artifact missing OR step memory count ≠ 8 OR validation not passed OR any content check fails

Critical: This gate would have prevented V1 from advancing with only 57% Recommend completion and caught V3's missing recommendation-selection.md.

Gate 5: ALIGN → DONE¶

Prerequisites - Artifacts¶

✅ align/artifacts/capability-thesis.md exists
✅ align/artifacts/execution-plan.md exists
✅ align/artifacts/alignment-record.md exists

Prerequisites - Validation¶

✅ align/validation/align-to-ready-gate.md created with decision
⚠️ align/validation/align-validation.md (optional quality validation)

Prerequisites - Memory¶

✅ Step memories: 4 files in align/memory/ named step-1.md through step-4.md (150-250 tokens each)
✅ Phase summary: align/memory/align-phase-summary.md exists (≤900 tokens)
✅ Workflow summary: workflow-summary.md exists (root level, 3,000-4,000 tokens)

Validation Command¶

# Artifact count check
ls align/artifacts/capability-thesis.md align/artifacts/execution-plan.md align/artifacts/alignment-record.md 2>/dev/null | wc -l
# Expected: 3

# Memory count
ls align/memory/step-*.md 2>/dev/null | wc -l
# Expected: 4

# Workflow summary
ls workflow-summary.md 2>/dev/null | wc -l
# Expected: 1

Content Compliance Checks (REQUIRED)¶

Capability Thesis Cross-Phase Integration:

# Check capability-thesis.md references all prior phases
grep -q "job" align/artifacts/capability-thesis.md && \
grep -q "P0" align/artifacts/capability-thesis.md && \
grep -q "RICE" align/artifacts/capability-thesis.md
# Expected: References job (Observe), P0 problems (Orient), RICE scores (Recommend)

RGRD Execution Plan:

# Check execution-plan.md contains RGRD milestones
grep -q "Red" align/artifacts/execution-plan.md && \
grep -q "Green" align/artifacts/execution-plan.md && \
grep -q "Refactor" align/artifacts/execution-plan.md && \
grep -q "Document" align/artifacts/execution-plan.md
# Expected: All 4 RGRD phases found (exit code 0)

Time Horizon Prioritization:

# Check execution-plan.md has time-based sequencing
grep -E -q "Now|Next|Near|Later" align/artifacts/execution-plan.md
# Expected: Time horizons from Orient prognosis (exit code 0)

Kano-Driven Sequencing:

# Check execution-plan.md references Must-Be requirements first
grep -q "Must-Be" align/artifacts/execution-plan.md || \
grep -q "baseline" align/artifacts/execution-plan.md
# Expected: Baseline/Must-Be requirements mentioned (exit code 0)

Workflow Summary Completeness:

# Check workflow-summary.md synthesizes all phases
grep -q "Observe" workflow-summary.md && \
grep -q "Orient" workflow-summary.md && \
grep -q "Recommend" workflow-summary.md && \
grep -q "Align" workflow-summary.md && \
grep -q "Kano" workflow-summary.md && \
grep -q "RICE" workflow-summary.md
# Expected: All phases + frameworks documented (exit code 0)

Block Condition: If any artifact missing OR step memory count ≠ 4 OR workflow summary missing OR any content check fails

🔒 Validation Gate Enforcement¶

How to Enforce¶

@workflow-manager runs validation checks before updating version.json workflow stage
If validation fails, version.json remains at current stage
Error message displayed with checklist of missing items
Phase cannot proceed until all prerequisites met

Example Error Message¶

❌ ORIENT → RECOMMEND Gate FAILED

Missing Prerequisites:
- ❌ orient/artifacts/symptoms-analysis.md (REQUIRED)
- ✅ orient/artifacts/diagnosis.md
- ❌ orient/artifacts/prognosis.md (REQUIRED)
- ✅ orient/artifacts/problem-statement.md
- ✅ orient/artifacts/kano-classification.md
- ❌ orient/artifacts/rice-prioritization.md (REQUIRED)
- ✅ orient/artifacts/problem-prioritization.md
- ✅ orient/artifacts/orient-validation.md
- ⚠️  Step memories: 6/9 present (step-6, step-7, step-8 MISSING)

Cannot proceed to Recommend phase. Complete missing artifacts and memories first.

Override: Not permitted. All prerequisites are mandatory.

📝 Step Memory Validation¶

Step Memory Requirements by Phase¶

MANDATORY: Every workflow step MUST create a step memory file.

Phase	Step Count	Step Memory Files	Location
CAPTURE	6	`step-1.md` to `step-6.md`	`capture/memory/`
OBSERVE	8	`step-1.md` to `step-8.md`	`observe/memory/`
ORIENT	11	`step-1.md` to `step-11.md`	`orient/memory/`
RECOMMEND	8	`step-1.md` to `step-8.md`	`recommend/memory/`
ALIGN	4	`step-1.md` to `step-4.md`	`align/memory/`
TOTAL	37	37 step memories	Across all phases

Step Memory Content Requirements¶

Each step memory MUST contain (see .contributing/templates/step-memory.md.template):

Header:
Step number and total (e.g., "Step 4/8 (OBSERVE)")
Agent name (@analyst, @ux-researcher, etc.)
Framework used (if applicable)
Completion timestamp (ISO 8601)
Body:
What was done (1-2 sentences)
Key outputs (3-5 bullets)
Key insights (2-3 bullets)
Next step (or "Phase complete")
Metadata:
JSON block with step number, phase, agent, framework, timestamp, token count
Token Budget:
Target: 150-250 tokens per step memory
Validation: Auto-compact if >250 tokens

Validation Script Example¶

#!/bin/bash
# validate-step-memories.sh - Check step memory completeness

CAPABILITY_PATH="$1"
PHASE="$2"
EXPECTED_STEPS="$3"

echo "Validating $PHASE step memories..."

# Count step memories
STEP_COUNT=$(ls "$CAPABILITY_PATH/$PHASE/memory/step-*.md" 2>/dev/null | wc -l)

if [ "$STEP_COUNT" -ne "$EXPECTED_STEPS" ]; then
  echo "❌ Step memory gap: Found $STEP_COUNT, expected $EXPECTED_STEPS"

  # Identify missing steps
  for i in $(seq 1 "$EXPECTED_STEPS"); do
    if [ ! -f "$CAPABILITY_PATH/$PHASE/memory/step-$i.md" ]; then
      echo "   Missing: step-$i.md"
    fi
  done

  exit 1
fi

# Validate token budgets
for step_file in "$CAPABILITY_PATH/$PHASE/memory/step-"*.md; do
  TOKEN_COUNT=$(wc -w < "$step_file" | awk '{print int($1 / 0.75)}')  # Approx: 1 token ≈ 0.75 words

  if [ "$TOKEN_COUNT" -gt 250 ]; then
    echo "⚠️  $(basename "$step_file"): $TOKEN_COUNT tokens (exceeds 250 budget)"
  fi
done

echo "✅ All $EXPECTED_STEPS step memories present"
exit 0

Usage:

./validate-step-memories.sh .roadmap/active/my-capability observe 8
./validate-step-memories.sh .roadmap/active/my-capability orient 11
./validate-step-memories.sh .roadmap/active/my-capability recommend 8
./validate-step-memories.sh .roadmap/active/my-capability align 4

🎯 Token Budget Enforcement¶

Phase Summary Token Budgets¶

Phase	Token Budget	Enforcement
CAPTURE	≤250 tokens	Strict (gate blocks if exceeded)
OBSERVE	≤900 tokens	Strict (gate blocks if exceeded)
ORIENT	≤900 tokens	Strict (gate blocks if exceeded)
RECOMMEND	≤900 tokens	Strict (gate blocks if exceeded)
ALIGN	≤900 tokens	Strict (gate blocks if exceeded)
Workflow Summary	3,000-4,000 tokens	Target range (warn if outside)

Token Budget Validation¶

#!/bin/bash
# validate-token-budgets.sh

CAPABILITY_PATH="$1"
PHASE="$2"
MAX_TOKENS="$3"  # 250 for CAPTURE, 900 for others

SUMMARY_FILE="$CAPABILITY_PATH/$PHASE/memory/$PHASE-phase-summary.md"

if [ ! -f "$SUMMARY_FILE" ]; then
  echo "❌ Phase summary missing: $SUMMARY_FILE"
  exit 1
fi

# Approximate token count (1 token ≈ 0.75 words)
WORD_COUNT=$(wc -w < "$SUMMARY_FILE")
TOKEN_COUNT=$(awk "BEGIN {print int($WORD_COUNT / 0.75)}")

if [ "$TOKEN_COUNT" -gt "$MAX_TOKENS" ]; then
  echo "❌ Token budget exceeded: $TOKEN_COUNT tokens > $MAX_TOKENS max"
  echo "   File: $SUMMARY_FILE"
  echo "   Action: Compress phase summary to meet budget"
  exit 1
fi

echo "✅ Token budget OK: $TOKEN_COUNT tokens ≤ $MAX_TOKENS max"
exit 0

Automated Compaction (if token budget exceeded): 1. Identify redundant phrases 2. Remove low-value details 3. Use abbreviations for repeated terms 4. Preserve critical numbers and decisions 5. Re-validate token count

🚀 Session-Per-Phase Architecture¶

Why Session-Per-Phase?¶

Problem: Single-session workflow accumulates 75,000+ tokens by ALIGN, causing: - Context decay (AI forgets earlier decisions) - Hallucinated cross-references - Incomplete artifact creation - Poor validation scores

Solution: Execute each phase in a separate AI session.

Session Benefits¶

Metric	Single Session	Session-Per-Phase	Improvement
Token Usage	~75,000 total	~3,500 per phase	95% reduction
Context Retention	Degrades to 60%	Stays at 95%	35% improvement
Artifact Completeness	23-40%	95%+ expected	55-72% improvement
Validation Scores	6.3-8.0/10	9.0+/10 expected	13-43% improvement

Session Handoff Pattern¶

Session N (OBSERVE) Ends: 1. Creates observe-phase-summary.md (≤900 tokens) 2. Creates observe-to-orient-gate.md (PASS decision) 3. Commits and exits

Session N+1 (ORIENT) Starts: 1. Loads observe-phase-summary.md (~900 tokens, not 25,000+) 2. Executes ORIENT workflow (11 steps) 3. Creates 11 step memories + phase summary 4. Creates gate decision and exits

Key Insight: Phase summaries are 95% smaller than raw artifacts, enabling fresh context per phase.

Related Documentation: - AGENTS.md - Main agent navigation - PROCESS-STANDARDS.md - Artifact requirements - MEMORY-PROTOCOL.md - Memory management rules

Referenced By: - .contributing/agent/workflow-manager.md - Primary gate enforcer - .contributing/agent/gate-keeper.md - Gate validation agent - All workflow phase agents

Validation Gates¶

🚦 Overview¶

Gate 1: CAPTURE → OBSERVE¶

Prerequisites - Artifacts¶

Prerequisites - Validation¶

Prerequisites - Memory¶

Validation Command¶

Gate 2: OBSERVE → ORIENT¶

Prerequisites - Artifacts¶

Prerequisites - Validation¶

Prerequisites - Memory¶

Validation Command¶

Gate 3: ORIENT → RECOMMEND¶

Prerequisites - Artifacts¶

Prerequisites - Validation¶

Prerequisites - Memory¶

Validation Command¶

Content Compliance Checks (REQUIRED)¶

Gate 4: RECOMMEND → ALIGN¶

Prerequisites - Artifacts¶

Prerequisites - Validation¶

Prerequisites - Memory¶

Validation Command¶

Content Compliance Checks (REQUIRED)¶

Gate 5: ALIGN → DONE¶

Prerequisites - Artifacts¶

Prerequisites - Validation¶

Prerequisites - Memory¶

Validation Command¶

Content Compliance Checks (REQUIRED)¶

🔒 Validation Gate Enforcement¶

How to Enforce¶

Example Error Message¶

📝 Step Memory Validation¶

Step Memory Requirements by Phase¶

Step Memory Content Requirements¶

Validation Script Example¶

🎯 Token Budget Enforcement¶

Phase Summary Token Budgets¶

Token Budget Validation¶

🚀 Session-Per-Phase Architecture¶

Why Session-Per-Phase?¶

Session Benefits¶

Session Handoff Pattern¶

Navigation¶