Deviation Handling

Deviation Handling Skill

The 4-Rule System

Rule 1: Bug Fixes (Auto-Fix)

Triggers:

• Type errors, null pointer exceptions
• Logic errors (off-by-one, wrong comparison)
• Security vulnerabilities (injection, XSS)
• Runtime crashes
• Memory leaks

Action: Fix immediately without asking.

Example:

// Bug found: missing null check
if (user.email) {  // Was: if (user) - crashes on undefined
  sendEmail(user.email);
}

Rule 2: Missing Critical Functionality (Auto-Fix)

Triggers:

• Missing error handling
• Missing input validation
• Missing auth checks
• Missing rate limiting
• Missing sanitization

Action: Add immediately without asking.

Example:

// Missing: input validation
export async function createUser(data: UserInput) {
  // Added: validation
  if (!isValidEmail(data.email)) {
    throw new ValidationError('Invalid email');
  }
  // ... rest of implementation
}

Rule 3: Blocking Issues (Auto-Fix)

Triggers:

• Missing npm packages
• Broken imports
• Missing env variables
• Config errors
• Build failures

Action: Fix to unblock without asking.

Example:

# Missing package
npm install zod  # Added to fix import error

Rule 4: Architectural Decisions (STOP)

Triggers:

• Database schema changes
• New tables or collections
• Framework switches
• Major dependency additions
• API contract changes
• Infrastructure changes

Action: STOP and ask user.

Example:

STOP: Architectural Decision Required

The current implementation requires a new database table
for session storage.

Options:
1. Add 'sessions' table (recommended)
2. Use in-memory session store
3. Use existing 'users' table with session fields

Please choose an option to continue.

Detection Flow

Issue Found
    │
    ▼
Is it a bug/error? ──Yes──► Rule 1: Auto-fix
    │
    No
    │
    ▼
Is critical feature missing? ──Yes──► Rule 2: Auto-add
    │
    No
    │
    ▼
Is it blocking progress? ──Yes──► Rule 3: Auto-fix
    │
    No
    │
    ▼
Is it architectural? ──Yes──► Rule 4: STOP and ask
    │
    No
    │
    ▼
Continue without deviation

Logging Deviations

Always log to ADL:

### AD-015

**Type:** implementation
**Date:** 2024-01-15T10:30:00Z
**Status:** active

**Context:**
During implementation of login endpoint, discovered missing
input validation on email field.

**Decision:**
Applied Rule 2: Auto-added email validation using zod schema.

**Rationale:**
Input validation is a critical security requirement that any
professional implementation would include.

**Related Files:**
- `src/auth/login.ts`

Confidence Handling

If unsure which rule applies:

• Default to Rule 4 (ask user)
• Log uncertainty in ADL
• Request clarification

Commit Messages

fix(auth): add missing email validation (Rule 2 deviation)

- Added zod schema for email validation
- Returns 400 on invalid input
- Logged as AD-015 in ADL

During: Implement login endpoint
Issue: Missing input validation
Rule: 2 (auto-add missing critical functionality)

Best Practices

1. Document everything: Every deviation goes in ADL
2. Atomic fixes: One deviation = one commit
3. Stay in scope: Deviations shouldn't expand spec scope
4. Confidence threshold: When in doubt, ask (Rule 4)
5. Verify after fix: Run tests to confirm fix works

Converted and distributed by TomeVault — claim your Tome and manage your conversions.