What is defense-in-depth?

The Defense-in-Depth Validation skill is a robust architectural pattern designed to eliminate software bugs caused by invalid data. Instead of relying on a single check, it implements a multi-layered validation strategy—covering entry points, business logic, environment guards, and debug instrumentation. This approach ensures data integrity across all execution layers, making complex system failures structurally impossible and significantly improving code reliability and maintainability.

When should I use defense-in-depth?

defense-in-depth is useful in the following scenarios: • Preventing deep-system crashes by catching malformed API inputs and invalid data at the initial entry boundary. • Hardening business logic against edge cases that might bypass standard validation during refactoring or unit testing with mocks. • Implementing environment guards to prevent dangerous operations (like file system modifications or database wipes) in restricted contexts like testing or production. • Enhancing forensic debugging by integrating stack traces and context-rich logging at critical data checkpoints to identify structural misuse.

name	defense-in-depth
description	Use when invalid data causes failures deep in execution - validates at every layer data passes through to make bugs structurally impossible

Defense-in-Depth Validation

Overview

When you fix a bug caused by invalid data, adding validation at one place feels sufficient. But that single check can be bypassed by different code paths, refactoring, or mocks.

Core principle: Validate at EVERY layer data passes through. Make the bug structurally impossible.

Why Multiple Layers

Single validation: "We fixed the bug" Multiple layers: "We made the bug impossible"

Different layers catch different cases:

Entry validation catches most bugs
Business logic catches edge cases
Environment guards prevent context-specific dangers
Debug logging helps when other layers fail

The Four Layers

Layer 1: Entry Point Validation

Purpose: Reject obviously invalid input at API boundary

function createProject(name: string, workingDirectory: string) {
  if (!workingDirectory || workingDirectory.trim() === '') {
    throw new Error('workingDirectory cannot be empty');
  }
  if (!existsSync(workingDirectory)) {
    throw new Error(`workingDirectory does not exist: ${workingDirectory}`);
  }
  // ... proceed
}

Layer 2: Business Logic Validation

Purpose: Ensure data makes sense for this operation

function initializeWorkspace(projectDir: string, sessionId: string) {
  if (!projectDir) {
    throw new Error('projectDir required for workspace initialization');
  }
  // ... proceed
}

Layer 3: Environment Guards

Purpose: Prevent dangerous operations in specific contexts

async function gitInit(directory: string) {
  // In tests, refuse git init outside temp directories
  if (process.env.NODE_ENV === 'test') {
    const normalized = resolve(directory);
    const tmpDir = resolve(tmpdir());

    if (!normalized.startsWith(tmpDir)) {
      throw new Error(
        `Refusing git init outside temp dir during tests: ${directory}`
      );
    }
  }
  // ... proceed
}

Layer 4: Debug Instrumentation

Purpose: Capture context for forensics

async function gitInit(directory: string) {
  const stack = new Error().stack;
  logger.debug('About to git init', {
    directory,
    cwd: process.cwd(),
    stack,
  });
  // ... proceed
}

Applying the Pattern

When you find a bug:

Trace the data flow - Where does bad value originate? Where used?
Map all checkpoints - List every point data passes through
Add validation at each layer - Entry, business, environment, debug
Test each layer - Try to bypass layer 1, verify layer 2 catches it

Example

Bug: Empty projectDir caused git init in source code

Data flow:

Test setup → empty string
Project.create(name, '')
WorkspaceManager.createWorkspace('')
git init runs in process.cwd()

Four layers added:

Layer 1: Project.create() validates not empty/exists/writable
Layer 2: WorkspaceManager validates projectDir not empty
Layer 3: WorktreeManager refuses git init outside tmpdir in tests
Layer 4: Stack trace logging before git init

Result: Bug impossible to reproduce

Key Insight

All four layers were necessary. During testing, each layer caught bugs the others missed:

Different code paths bypassed entry validation
Mocks bypassed business logic checks
Edge cases on different platforms needed environment guards
Debug logging identified structural misuse

Don't stop at one validation point. Add checks at every layer.

Integration

Used by:

systematic-debugging - After finding root cause, add defense-in-depth
root-cause-tracing - Add validation at each layer traced

Complements:

security-check - Defense-in-depth for security validations

defense-in-depth

When & Why to Use This Skill

Use Cases