Back to catalog

TDD-discipline

Skill from elevanaltd/oa

• Category: discovered
• Tags: github, community
• Version: 1.0.0
• Author: walid
• Downloads: 0
• Updated: 2025-11-22

• Source: elevanaltd/oa

Download the latest version (v1.0.0) from this page.

SKILL.md

# TDD Discipline Skill (FLUKE)
## Test-Driven Development Enforcement

> **TYPE**: Guardrail Skill (FLUKE)
> **CATEGORY**: Quality Enforcement
> **PRIORITY**: Critical
> **AUTO_INJECT**: true (in ACTUAL ARM only)

---

## Skill Purpose

This skill provides **rigorous TDD discipline** ensuring test-first development with verifiable evidence.

**Core Principle**: "Failing test BEFORE implementation - NO EXCEPTIONS."

---

## When This Skill Activates

**Trigger Keywords**:
- "implement"
- "add feature"
- "build"
- "create function"
- "write code"

**ARM Context Filter**: **ACTUAL ARM ONLY**
- Activated in: B0, B1, B2, B3, B4, B5
- Suppressed in: D0, D1, D2, D3 (no code in CONCEPTUAL)

**Affinity Skills** (co-loaded):
- `build-execution`
- `verification-protocols`
- `system-architecture`

---

## The Sacred Cycle: RED → GREEN → REFACTOR

### RED Phase: Write Failing Test

**Actions**:
```
1. Write test describing desired behavior
2. Run test → MUST FAIL
3. Verify fails for CORRECT reason
   ✓ Expected failure: Feature not implemented
   ✗ Wrong failure: Syntax error, missing import
```

**Git Commit**:
```bash
git commit -m "TEST: Add failing test for user authentication"
```

**Evidence Required**:
```
$ npm test
FAIL tests/auth.test.ts
  ✕ authenticates user with valid credentials (5ms)

Expected: User authenticated
Received: Not implemented

Tests: 1 failed, 1 total
```

**Why This Matters**:
- Proves test actually validates behavior (not broken test)
- Documents expected behavior before coding
- Prevents retroactive test writing (common shortcut)

---

### GREEN Phase: Minimal Implementation

**Actions**:
```
1. Write MINIMAL code to pass test
2. Run test → MUST PASS
3. Resist "while I'm here" feature additions
```

**Minimal Intervention Principle**:
```typescript
// WRONG: Full-featured implementation
function authenticate(username, password) {
  const user = await db.findUser(username);
  const valid = await bcrypt.compare(password, user.hash);
  if (!valid) throw new Error('Invalid credentials');
  const token = jwt.sign({ userId: user.id }, SECRET);
  await logAuthAttempt(user.id, true);
  await updateLastLogin(user.id);
  return { user, token };
}

// RIGHT: Minimal code to pass test
function authenticate(username, password) {
  if (username === 'test' && password === 'pass') {
    return { authenticated: true };
  }
  throw new Error('Invalid credentials');
}
```

**Why Minimal Matters**:
- Forces clarity about requirements
- Prevents premature optimization
- Reveals missing test coverage
- Enables faster iteration

**Git Commit**:
```bash
git commit -m "FEAT: Implement basic authentication to pass test"
```

**Evidence Required**:
```
$ npm test
PASS tests/auth.test.ts
  ✓ authenticates user with valid credentials (3ms)

Tests: 1 passed, 1 total
```

---

### REFACTOR Phase: Improve While Green

**Actions**:
```
1. Identify duplication or complexity
2. Refactor in SMALL steps
3. Run tests after EACH step
4. IF[fail] → Revert immediately
```

**Example Refactoring**:
```typescript
// Step 1: Extract validation
function authenticate(username, password) {
  validateCredentials(username, password); // Extracted
  return { authenticated: true };
}

// Run tests → Still GREEN? Continue

// Step 2: Add real database lookup
function authenticate(username, password) {
  const user = await db.findUser(username);
  validateCredentials(username, password, user);
  return { authenticated: true, user };
}

// Run tests → Still GREEN? Continue

// Step 3: Add JWT token generation
function authenticate(username, password) {
  const user = await db.findUser(username);
  validateCredentials(username, password, user);
  const token = generateToken(user);
  return { authenticated: true, user, token };
}

// Run tests → Still GREEN? Done
```

**Git Commit** (after each successful refactor):
```bash
git commit -m "REFACTOR: Extract credential validation"
git commit -m "REFACTOR: Add database user lookup"
git commit -m "REFACTOR: Add JWT token generation"
```

**Why Small Steps Matter**:
- Isolates breaking changes
- Fast feedback loop
- Easy rollback
- Maintains confidence

---

## Evidence Requirements

### Git History Validation

**CORRECT Sequence**:
```
commit abc123 "REFACTOR: Simplify token generation"
commit def456 "FEAT: Implement authentication to pass test"
commit ghi789 "TEST: Add failing test for user authentication"
```

**INCORRECT Sequence** (VIOLATION):
```
commit abc123 "feat: Add authentication with tests"
(Single commit = retroactive tests = TDD violation)
```

### Test Output Evidence

Every implementation claim requires:
```
BEFORE (RED):
$ npm test
FAIL tests/auth.test.ts ✕ 1 test failed

AFTER (GREEN):
$ npm test
PASS tests/auth.test.ts ✓ 1 test passed
```

### Coverage Requirements

**Minimum**: 80% code coverage
**Target**: 95% code coverage
**Critical paths**: 100% coverage (auth, payments, data loss scenarios)

**Evidence**:
```
$ npm run coverage
Coverage: 94.2% of statements
  auth.ts: 100%
  users.ts: 92%
  utils.ts: 87%
```

---

## Common Violations & Enforcement

### ❌ Violation 1: Retroactive Tests
```bash
# RED FLAG: Implementation and test in same commit
git commit -m "Add authentication feature with tests"
```

**Enforcement**: Code review blocks merge
**Consequence**: Rework required

### ❌ Violation 2: Skipped Test Phase
```typescript
// Implementing without test
function newFeature() {
  // "I'll add tests later"
  return implementation;
}
```

**Enforcement**: Pre-commit hook checks test file modifications
**Consequence**: Commit rejected

### ❌ Violation 3: Non-Failing Red Phase
```typescript
// Test passes immediately (not a real test)
test('feature works', () => {
  expect(true).toBe(true); // Meaningless
});
```

**Enforcement**: Code review identifies trivial tests
**Consequence**: Test improvement required

### ❌ Violation 4: "While I'm Here" Additions
```typescript
// In PR titled "Add authentication"
function authenticate() { /* ... */ }
function generateReport() { /* VIOLATION: Unrelated feature */ }
function optimizeCache() { /* VIOLATION: Unrelated optimization */ }
```

**Enforcement**: PR review scope validation
**Consequence**: Split PR, focus on single responsibility

---

## ARM Context: ACTUAL Only

### Why Suppressed in CONCEPTUAL ARM?

**CONCEPTUAL ARM (D0-D3)**: No code implementation
- TDD discipline irrelevant (not coding yet)
- Skill confidence: -0.50 (strong suppression)

**ACTUAL ARM (B0-B5)**: Active implementation
- TDD discipline mandatory
- Skill confidence: +0.40 (strong boost)

**Transition**: At B0_THEMIS gate, TDD activates

---

## Integration with Build Execution

### Mandatory Protocol Sequence

```
1. Load TDD-discipline skill (this file)
2. Load build-execution skill (overall strategy)
3. Load verification-protocols (evidence requirements)

TodoWrite: "Protocol loaded: TDD + MIP + Verification"
```

### Quality Gate Enforcement

**CI Pipeline Checks**:
```yaml
tdd-validation:
  - Check: Test files modified with implementation files
  - Check: Commit message patterns (TEST → FEAT → REFACTOR)
  - Check: Coverage threshold met (80%+)
  - Check: All tests pass
  - Block: If any check fails
```

---

## Success Evidence

**This skill succeeds when**:
- ✅ Git history shows TEST commit before FEAT commit
- ✅ Test output proves RED state before implementation
- ✅ Coverage meets or exceeds threshold
- ✅ All tests pass in CI
- ✅ Code review approves TDD compliance

**Example Success Evidence**:
```markdown
## TDD Compliance Evidence

### Git History
- commit abc123 "TEST: Add failing auth test" (RED)
- commit def456 "FEAT: Implement auth" (GREEN)
- commit ghi789 "REFACTOR: Extract validation" (REFACTOR)

### Test Output
RED phase: 1 failed, 0 passed
GREEN phase: 1 passed, 0 failed

### Coverage
auth.ts: 100% (15/15 statements)

### CI Status
✅ All checks passed
```

---

## LOGOS Cognition Alignment

**Why TDD Aligns with LOGOS**:

1. **Systematic Thinking**: TDD enforces systematic progression
2. **Empirical Validation**: Tests provide reality checks
3. **Synthesis**: Refactoring synthesizes better solutions
4. **Evidence-Based**: All claims verified by tests

**Affinity**: LOGOS agents receive +0.15 boost with TDD skill

---

**VERSION**: 1.0.0
**LAST_UPDATED**: 2025-11-15
**MAINTAINER**: holistic-orchestrator
**STATUS**: Active (enforced in ACTUAL ARM)