Classeo/.agents/skills/bmad-testarch-trace/steps-c/step-05-gate-decision.md

---
name: 'step-05-gate-decision'
description: 'Phase 2: Apply gate decision logic and generate outputs'
outputFile: '{test_artifacts}/traceability-report.md'
---

# Step 5: Phase 2 - Gate Decision

## STEP GOAL

**Phase 2:** Read coverage matrix from Phase 1, apply deterministic gate decision logic, and generate traceability report.

---

## MANDATORY EXECUTION RULES

- 📖 Read the entire step file before acting
- ✅ Speak in `{communication_language}`
- ✅ Read coverage matrix from Phase 1 temp file
- ✅ Apply gate decision logic
- ❌ Do NOT regenerate coverage matrix (use Phase 1 output)

---

## EXECUTION PROTOCOLS:

- 🎯 Follow the MANDATORY SEQUENCE exactly
- 💾 Record outputs before proceeding
- 📖 This is the FINAL step

## CONTEXT BOUNDARIES:

- Available context: Coverage matrix from Phase 1 temp file
- Focus: gate decision logic only
- Dependencies: Phase 1 complete (coverage matrix exists)

---

## MANDATORY SEQUENCE

### 1. Read Phase 1 Coverage Matrix

```javascript
const matrixPath = '/tmp/tea-trace-coverage-matrix-{{timestamp}}.json';
const coverageMatrix = JSON.parse(fs.readFileSync(matrixPath, 'utf8'));

console.log('✅ Phase 1 coverage matrix loaded');
```

**Verify Phase 1 complete:**

```javascript
if (coverageMatrix.phase !== 'PHASE_1_COMPLETE') {
  throw new Error('Phase 1 not complete - cannot proceed to gate decision');
}
```

---

### 2. Apply Gate Decision Logic

**Decision Tree:**

```javascript
const stats = coverageMatrix.coverage_statistics;
const p0Coverage = stats.priority_breakdown.P0.percentage;
const p1Coverage = stats.priority_breakdown.P1.percentage;
const hasP1Requirements = (stats.priority_breakdown.P1.total || 0) > 0;
const effectiveP1Coverage = hasP1Requirements ? p1Coverage : 100;
const overallCoverage = stats.overall_coverage_percentage;
const criticalGaps = coverageMatrix.gap_analysis.critical_gaps.length;

let gateDecision;
let rationale;

// Rule 1: P0 coverage must be 100%
if (p0Coverage < 100) {
  gateDecision = 'FAIL';
  rationale = `P0 coverage is ${p0Coverage}% (required: 100%). ${criticalGaps} critical requirements uncovered.`;
}
// Rule 2: Overall coverage must be >= 80%
else if (overallCoverage < 80) {
  gateDecision = 'FAIL';
  rationale = `Overall coverage is ${overallCoverage}% (minimum: 80%). Significant gaps exist.`;
}
// Rule 3: P1 coverage < 80% → FAIL
else if (effectiveP1Coverage < 80) {
  gateDecision = 'FAIL';
  rationale = hasP1Requirements
    ? `P1 coverage is ${effectiveP1Coverage}% (minimum: 80%). High-priority gaps must be addressed.`
    : `P1 requirements are not present; continuing with remaining gate criteria.`;
}
// Rule 4: P1 coverage >= 90% and overall >= 80% with P0 at 100% → PASS
else if (effectiveP1Coverage >= 90) {
  gateDecision = 'PASS';
  rationale = hasP1Requirements
    ? `P0 coverage is 100%, P1 coverage is ${effectiveP1Coverage}% (target: 90%), and overall coverage is ${overallCoverage}% (minimum: 80%).`
    : `P0 coverage is 100% and overall coverage is ${overallCoverage}% (minimum: 80%). No P1 requirements detected.`;
}
// Rule 5: P1 coverage 80-89% with P0 at 100% and overall >= 80% → CONCERNS
else if (effectiveP1Coverage >= 80) {
  gateDecision = 'CONCERNS';
  rationale = hasP1Requirements
    ? `P0 coverage is 100% and overall coverage is ${overallCoverage}% (minimum: 80%), but P1 coverage is ${effectiveP1Coverage}% (target: 90%).`
    : `P0 coverage is 100% and overall coverage is ${overallCoverage}% (minimum: 80%), but additional non-P1 gaps need mitigation.`;
}

// Rule 6: Manual waiver option
const manualWaiver = false; // Can be set via config or user input
if (manualWaiver) {
  gateDecision = 'WAIVED';
  rationale += ' Manual waiver applied by stakeholder.';
}
```

---

### 3. Generate Gate Report

```javascript
const gateReport = {
  decision: gateDecision,
  rationale: rationale,
  decision_date: new Date().toISOString(),

  coverage_matrix: coverageMatrix,

  gate_criteria: {
    p0_coverage_required: '100%',
    p0_coverage_actual: `${p0Coverage}%`,
    p0_status: p0Coverage === 100 ? 'MET' : 'NOT MET',

    p1_coverage_target_pass: '90%',
    p1_coverage_minimum: '80%',
    p1_coverage_actual: `${effectiveP1Coverage}%`,
    p1_status: effectiveP1Coverage >= 90 ? 'MET' : effectiveP1Coverage >= 80 ? 'PARTIAL' : 'NOT MET',

    overall_coverage_minimum: '80%',
    overall_coverage_actual: `${overallCoverage}%`,
    overall_status: overallCoverage >= 80 ? 'MET' : 'NOT MET',
  },

  uncovered_requirements: coverageMatrix.gap_analysis.critical_gaps.concat(coverageMatrix.gap_analysis.high_gaps),

  recommendations: coverageMatrix.recommendations,
};
```

---

### 4. Generate Traceability Report

**Use trace-template.md to generate:**

```markdown
# Traceability Report

## Gate Decision: {gateDecision}

**Rationale:** {rationale}

## Coverage Summary

- Total Requirements: {totalRequirements}
- Covered: {fullyCovered} ({coveragePercentage}%)
- P0 Coverage: {p0CoveragePercentage}%

## Traceability Matrix

[Full matrix with requirement → test mappings]

## Gaps & Recommendations

[List of uncovered requirements with recommended actions]

## Next Actions

{recommendations}
```

**Save to:**

```javascript
fs.writeFileSync('{outputFile}', reportContent, 'utf8');
```

---

### 5. Display Gate Decision

```
🚨 GATE DECISION: {gateDecision}

📊 Coverage Analysis:
- P0 Coverage: {p0Coverage}% (Required: 100%) → {p0_status}
- P1 Coverage: {effectiveP1Coverage}% (PASS target: 90%, minimum: 80%) → {p1_status}
- Overall Coverage: {overallCoverage}% (Minimum: 80%) → {overall_status}

✅ Decision Rationale:
{rationale}

⚠️ Critical Gaps: {criticalGaps.length}

📝 Recommended Actions:
{list top 3 recommendations}

📂 Full Report: {outputFile}

{if FAIL}
🚫 GATE: FAIL - Release BLOCKED until coverage improves
{endif}

{if CONCERNS}
⚠️ GATE: CONCERNS - Proceed with caution, address gaps soon
{endif}

{if PASS}
✅ GATE: PASS - Release approved, coverage meets standards
{endif}
```

---

### 6. Save Progress

**Update the YAML frontmatter in `{outputFile}` to mark this final step complete.**

Since step 4 (Generate Traceability Report) already wrote the report content to `{outputFile}`, do NOT overwrite it. Instead, update only the frontmatter at the top of the existing file:

- Add `'step-05-gate-decision'` to `stepsCompleted` array (only if not already present)
- Set `lastStep: 'step-05-gate-decision'`
- Set `lastSaved: '{date}'`

Then append the gate decision summary (from section 5 above) to the end of the existing report content.

---

## EXIT CONDITION

**WORKFLOW COMPLETE when:**

- ✅ Phase 1 coverage matrix read successfully
- ✅ Gate decision logic applied
- ✅ Traceability report generated
- ✅ Gate decision displayed

**Workflow terminates here.**

---

## 🚨 PHASE 2 SUCCESS METRICS

### ✅ SUCCESS:

- Coverage matrix read from Phase 1
- Gate decision made with clear rationale
- Report generated and saved
- Decision communicated clearly

### ❌ FAILURE:

- Could not read Phase 1 matrix
- Gate decision logic incorrect
- Report missing or incomplete

**Master Rule:** Gate decision MUST be deterministic based on clear criteria (P0 100%, P1 90/80, overall >=80).