# Phase 02: Test-First Design (Red Phase)

**Purpose:** Write failing tests from acceptance criteria before implementation.
**Execution Order:** After Phase 01 (Pre-Flight Validation)
**Expected Outcome:** All tests RED (failing), ready for implementation

---

## Phase Progress Indicator

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Phase 02/10: Test-First Design - Red Phase (10% → 20% complete)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

**Display this indicator at the start of Phase 02 execution.**

---

## Story Type Skip Check [MANDATORY FIRST] (STORY-126)

```
IF $STORY_TYPE == "refactor":
    Display: "  SKIPPING PHASE 02: Story Type 'refactor'"
    Display: "  Reason: Refactor stories work with existing tests."
    Display: "  Proceeding to Phase 03 (Green - Implementation)..."
    GOTO Phase 03
    RETURN
```

---

## Remediation Mode Check [MANDATORY AFTER SKIP CHECK]

```
IF $REMEDIATION_MODE == true:
    Display: "  REMEDIATION MODE - Phase 02R (Targeted Tests)"

    Read(file_path="references/qa-remediation-workflow.md")
    # Execute Phase 02R: Targeted Test Generation for $QA_COVERAGE_GAPS files only
    RETURN after Phase 02R completes

ELSE:
    # Normal Phase 02 - full story test generation
```

**Key distinction:** Remediation mode targets `$QA_COVERAGE_GAPS` files; normal mode covers full story AC.

---

## Phase 02: Test-First Design (Red Phase)

**Delegate test generation to test-automator subagent.**

### Step 0: Read source-tree.md Context [MANDATORY - STORY-206]

**Purpose:** Defense in depth - skill reads source-tree.md (Layer 1), test-automator reads independently (Layer 2, STORY-203).

```
Read(file_path="devforgeai/specs/context/source-tree.md")
```

**Test directory mapping:**

| Module Path | Expected Test Directory | Rule Source |
|-------------|------------------------|-------------|
| `installer/*` | `installer/tests/` | source-tree.md lines 384-443 |
| `.claude/scripts/devforgeai_cli/*` | `.claude/scripts/devforgeai_cli/tests/` | source-tree.md lines 299-309 |
| `src/*` | `tests/` (default) | source-tree.md lines 352 |

```
$MODULE_PATH = story.technical_specification.components[0].file_path

IF $MODULE_PATH starts with "installer/":
    $TEST_DIRECTORY = "installer/tests/"
ELIF $MODULE_PATH starts with ".claude/scripts/devforgeai_cli/":
    $TEST_DIRECTORY = ".claude/scripts/devforgeai_cli/tests/"
ELSE:
    $TEST_DIRECTORY = "tests/"
```

Set context markers BEFORE test-automator invocation:
```markdown
**Module Under Test:** ${MODULE_PATH}
**Expected Test Directory:** ${TEST_DIRECTORY} (per source-tree.md)
**Constraint:** All generated tests must be placed in ${TEST_DIRECTORY}
```

---

### Step 1: Invoke test-automator Subagent [MANDATORY]

```
Task(
  subagent_type="test-automator",
  description="Generate failing tests from acceptance criteria",
  prompt="Generate comprehensive test suite for this story.

  Story content is already loaded in conversation (via @file reference from /dev command).

  Extract from story:
  1. Acceptance criteria (Given/When/Then scenarios)
  2. Technical specification (API contracts, data models, business rules)
  3. Non-functional requirements (performance, security)

  Context files available:
  - devforgeai/specs/context/source-tree.md (test file placement rules)
  - devforgeai/specs/context/coding-standards.md (test patterns, AAA format)
  - devforgeai/specs/context/tech-stack.md (test framework: {TEST_FRAMEWORK})

  **source-tree.md Context for test file placement:**
  - Module Under Test: ${MODULE_PATH}
  - Expected Test Directory: ${TEST_DIRECTORY} (per source-tree.md)
  - Constraint: All generated tests must be placed in ${TEST_DIRECTORY}

  Generate tests that:
  1. Cover all acceptance criteria
  2. Follow AAA pattern (Arrange, Act, Assert)
  3. Use test framework: {TEST_FRAMEWORK}
  4. Place tests according to source-tree.md rules in ${TEST_DIRECTORY}
  5. Initially FAIL (Red phase of TDD)

  Test command to verify: {TEST_COMMAND}

  Return:
  - Test files created (paths and content summary)
  - Test count (unit/integration/e2e)
  - Initial test run status (all should fail)

  **Treelint Integration:** This subagent is Treelint-enabled. For AST-aware code search on supported languages, use Treelint patterns from `.claude/agents/references/treelint-search-patterns.md`. Fallback to Grep when unavailable."
)
```

### Step 2: Parse Subagent Response [MANDATORY]

```javascript
result = extract_from_subagent_output(response)
tests_created = result["test_files"]
test_count = result["test_count"]

Display: "Phase 02 (Red): Tests generated by test-automator"
Display: "  - Unit tests: {test_count['unit']}"
Display: "  - Integration tests: {test_count['integration']}"
Display: "  - Files created: {len(tests_created)}"
FOR file in tests_created:
    Display: "    {file['path']}"
```

### Step 3: Verify Tests Fail (Red Phase) [MANDATORY]

```
Bash(command=TEST_COMMAND)

IF all tests fail (as expected):
    Display: "RED phase confirmed - all tests failing as expected"

ELIF some tests pass:
    Display: "Warning: Some tests passing unexpectedly"
    Display: "  May indicate existing implementation or incorrect test design"
    Display: "  Proceeding to Phase 03..."

ELSE (tests not runnable):
    Display: "ERROR: Tests not runnable - review test-automator output"
    HALT development
```

---

### Step 4: Technical Specification Coverage Validation & Deferral Pre-Approval [MANDATORY]

**Purpose:** Ensure ALL Technical Specification components have tests. Prevents autonomous deferrals where stubs pass tests but skip real implementation.

**Execution:** After Steps 1-3, before Phase 03.

#### 4.1 Extract Technical Specification Components

Story file already loaded via @file reference from /dev command.

**RCA-006: Detect format version from frontmatter:**
```python
format_version = frontmatter.get("format_version", "1.0")
```

**If format_version == "2.0" (Structured YAML):**
```python
tech_spec = yaml.safe_load(tech_spec_yaml)
components = tech_spec["technical_specification"]["components"]

for component in components:
    component_checklist.append({
        "type": component["type"],
        "name": component["name"],
        "path": component["file_path"],
        "requirements": component.get("requirements", [])
    })

business_rules = tech_spec["technical_specification"].get("business_rules", [])
nfrs = tech_spec["technical_specification"].get("non_functional_requirements", [])
```

**If format_version == "1.0" (Freeform Text) - LEGACY:**

Extract components from these subsections:
1. **File Structure** - Parse directory tree for file paths
2. **Service Implementation Pattern** - Extract classes/methods
3. **Configuration Requirements** - Identify config files
4. **Logging Requirements** - Identify logging setup
5. **Data Models** - Extract entities/tables
6. **Business Rules** - Extract numbered rules requiring validation

Build component checklist with type, name, file path, and requirements array.

---

#### 4.2 Compare Generated Tests vs. Technical Specification

```
Glob(pattern="tests/**/*.cs")  # or *.py, *.js based on tech stack
```

For each test file, search for component coverage:
```
Read(file_path="{test_file}")
Grep(pattern="{component_name}", path="{test_file}")
```

Build coverage map per component: tests found, requirements covered, requirements missing, coverage percentage. Calculate overall totals.

---

#### 4.3 Present Coverage Analysis to User

**If coverage gaps detected (COVERAGE_GAP_COUNT > 0):**

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  TECHNICAL SPECIFICATION COVERAGE ANALYSIS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Story: {STORY_ID}
Phase: 02 (RED - Test Generation)

Components: {N} | Requirements: {N} | Tests: {N} | Coverage: {N}%

COVERAGE GAPS DETECTED: {N} requirements lack tests

Gap Summary:
{Per-component gap listing with covered/missing items}

PHASE 02 INCOMPLETE: Technical specification not fully covered by tests

Proceeding with gaps results in:
- Minimal implementations (stubs passing interface tests only)
- Silent deferred work accumulation
- Undocumented technical debt

USER DECISION REQUIRED for each gap (next step).
```

---

#### 4.4 Request User Decision for EACH Gap

**MANDATORY:** Use AskUserQuestion for EVERY coverage gap. Batch by component (max 5 questions).

```python
AskUserQuestion(
    questions=[{
        "question": "{ComponentName} has {N} missing tests. How should we proceed?",
        "header": "{Component} Tests",
        "multiSelect": False,
        "options": [
            {"label": "Generate tests now", "description": "Add tests (~15 min). RECOMMENDED - Prevents technical debt."},
            {"label": "Defer to follow-up story", "description": "Skip now, create tracking story. Creates technical debt."},
            {"label": "Remove from scope", "description": "Update story to remove requirements. Requires ADR."}
        ]
    }]
)
```

---

#### 4.5 Process User Decision

**Generate tests now:** Re-invoke test-automator with specific missing requirements. Add to Phase 02 test suite.

**Defer to follow-up story:**
- Ask user: create new story or use existing story ID
- If new: invoke `Skill(command="spec-driven-stories")`
- Document deferral record: component, requirements, reason, follow-up story, user approval timestamp
- Add to Phase 06 tracking

**Remove from scope:**
- Require ADR documenting why requirements removed
- HALT Phase 02 until ADR created and story file updated
- Re-run /dev after updates complete

---

#### 4.6 Repeat for All Gaps

Process EACH component with gaps. Update coverage map with user decisions. Track all decisions in `DECISIONS_LOG` array.

---

#### 4.7 Validate All Gaps Addressed

```python
unapproved_gaps = [gap for gap in COVERAGE_MAP.values()
                   if gap["requirements_missing"] and "decision" not in gap]

if unapproved_gaps:
    raise ValidationError(
        f"CANNOT PROCEED TO PHASE 03: {len(unapproved_gaps)} unapproved coverage gaps"
    )
```

---

#### 4.8 Document Decisions in Story File

Update story `## Workflow History` with:
- Component count, requirement count, gap count
- Per-component: decision type, tests added or follow-up story reference
- Phase 02 result summary with deferral counts

---

#### 4.9 Special Case: Zero Gaps

If `COVERAGE_GAP_COUNT == 0`: Display 100% coverage confirmation, skip Steps 4.4-4.7, proceed to Phase 03.

---

#### Step 4 Success Criteria

- [ ] All Technical Specification components extracted
- [ ] Coverage map built (tests vs. requirements)
- [ ] User made decision for EVERY coverage gap
- [ ] All decisions documented in workflow history
- [ ] Zero unapproved gaps remaining

---

## Subagents Invoked

**test-automator:** Generates failing tests from AC, places per source-tree.md, follows coding-standards.md patterns, uses tech-stack.md framework.

---

### Step 5: Update AC Verification Checklist (Phase 02 Items) [RCA-011]

**Purpose:** Check off AC items related to test generation (real-time progress tracking).

**Execution:** After Step 4, before Phase 02 checkpoint.

```
Read(file_path="references/ac-checklist-update-workflow.md")
```

Search story for Phase 02 AC items:
```
Grep(pattern="Phase.*: 1", path="${STORY_FILE}", output_mode="content", -B=1)
```

For each item with "**Phase:** 1" marker, validate completion and update:
```
Edit(
  file_path="${STORY_FILE}",
  old_string="- [ ] {item_text} - **Phase:** 1",
  new_string="- [x] {item_text} - **Phase:** 1"
)
```

Display progress: `"AC Progress: {checked}/{total} items complete ({percentage}%)"`

**Graceful Skip:** If AC Verification Checklist section not found, display info message and continue.

---

### Reflection Capture on Failure (EPIC-051)

**When:** AFTER phase validation fails, BEFORE retry attempt.

**Step 1: Generate Reflection**
```json
{
  "id": "REF-02-{timestamp}",
  "phase": "02",
  "failed": true,
  "iteration": "{count_existing_phase_02_reflections + 1}",
  "reflection": {
    "what_happened": "[Specific test failure: test name, assertion error, line number]",
    "why_it_failed": "[Root cause: incorrect expected value, missing setup, wrong assertion]",
    "how_to_improve": "[Actionable fix: re-read AC#N, check test setup, verify assertion]"
  },
  "timestamp": "{ISO8601_format}"
}
```

**Step 2:** Read existing reflections from `devforgeai/workflows/${STORY_ID}-phase-state.json`, calculate iteration count.

**Step 3:** Append reflection to phase state reflections[] array.

**Step 4:** On retry (iteration > 1), display previous reflection's what/why/how before starting.

**ID uniqueness:** `REF-{phase}-{timestamp}` with millisecond precision ensures no collisions.

**Error handling:** Reflection capture failure logs warning but never blocks retry (NFR-002).

---

## Pre-Implementation Baseline Tracking

Before executing the RED phase test suite, pre-implementation test results should be recorded as a baseline. This baseline captures which tests pass before any implementation code is written.

### Baseline Recording

Run tests once before implementation and record the results:

```
Bash(command=TEST_COMMAND)
# Record: which tests pass, which tests fail
# Save as baseline for comparison
```

### Baseline Evaluation

After recording, evaluate each result:

- **Tests that fail at baseline** — Expected. These are correctly written RED phase tests.
- **Tests passing at baseline** — Require explicit justification before proceeding.

tests passing at baseline require explicit justification before proceeding. Document the justification in the workflow history or request the test be strengthened to target the new (not existing) behavior.

### Baseline Documentation

Record baseline results in the workflow history:

```
Baseline: {pass_count} passing, {fail_count} failing
Tests passing at baseline: {list of test names if any}
Justification for passing tests: {reason or "N/A - none passing"}
```

---

## PHASE 02 COMPLETION CHECKPOINT

**Before proceeding to Phase 03, verify ALL steps executed:**

### Mandatory Steps

- [ ] **Step 1:** test-automator invoked, tests generated for all AC
- [ ] **Step 2:** Response parsed, test counts displayed
- [ ] **Step 3:** Tests verified RED (all failing via {TEST_COMMAND})
- [ ] **Step 4:** Technical Specification Coverage Validation complete
  - [ ] 4.1: Components extracted
  - [ ] 4.2: Coverage analysis generated
  - [ ] 4.3: Gaps presented to user
  - [ ] 4.4: User decisions captured for ALL gaps
  - [ ] 4.5-4.6: Decisions processed and documented
  - [ ] 4.7: Zero unapproved gaps
  - [ ] 4.8: Decisions in story file
- [ ] **Step 5:** AC Verification Checklist updated (or gracefully skipped)

### Success Criteria

- [ ] All AC have failing tests
- [ ] Tests placed correctly (per source-tree.md)
- [ ] All tests FAIL initially (Red phase verified)
- [ ] Test command executable ({TEST_COMMAND} runs)
- [ ] Tech Spec 100% covered OR gaps explicitly user-approved
- [ ] Zero autonomous deferrals

### Checkpoint Validation

**IF ANY ITEM UNCHECKED:**
```
PHASE 02 INCOMPLETE - Review missing steps above
DO NOT PROCEED TO PHASE 03 until all checkpoints pass

Most commonly missed:
  - Step 4 (Tech Spec Coverage Validation) - often skipped
  - User approval for coverage gaps - required for EVERY gap
  - Documentation of decisions - must update story file
```

**IF ALL ITEMS CHECKED:**
```
PHASE 02 COMPLETE - Test-First Design (Red Phase) Done

Tests: {test_count} | AC covered: {AC_count} | Components: {component_count} | Gaps addressed: {gap_count}

All tests are RED (failing). Ready to implement.

**Update Progress Tracker:** Mark "Execute Phase 02" todo as "completed"

Next: Load tdd-green-phase.md and execute Phase 03 (Implementation - Green Phase)
```
