Codewalkers/docs/archive/deviation-rules.md

# Deviation Rules

During execution, agents discover work not in the original plan. These rules define how to handle deviations **automatically, without asking for permission** (except Rule 4).

## The Four Rules

### Rule 1: Auto-Fix Bugs
**No permission needed.**

Fix immediately when encountering:
- Broken code (syntax errors, runtime errors)
- Logic errors (wrong conditions, off-by-one)
- Security issues (injection vulnerabilities, exposed secrets)
- Type errors (TypeScript violations)

```yaml
deviation:
  rule: 1
  type: bug_fix
  description: "Fixed null reference in user lookup"
  location: src/services/auth.ts:45
  original_code: "user.email.toLowerCase()"
  fixed_code: "user?.email?.toLowerCase() ?? ''"
  reason: "Crashes when user not found"
```

### Rule 2: Auto-Add Missing Critical Functionality
**No permission needed.**

Add immediately when clearly required:
- Error handling (try/catch for external calls)
- Input validation (user input, API boundaries)
- Authentication checks (protected routes)
- CSRF protection
- Rate limiting (if pattern exists in codebase)

```yaml
deviation:
  rule: 2
  type: missing_critical
  description: "Added input validation to createUser"
  location: src/api/users.ts:23
  added: "Zod schema validation for email, password length"
  reason: "API accepts any input without validation"
```

### Rule 3: Auto-Fix Blocking Issues
**No permission needed.**

Fix immediately when blocking task completion:
- Missing dependencies (npm install)
- Broken imports (wrong paths, missing exports)
- Configuration errors (env vars, tsconfig)
- Build failures (compilation errors)

```yaml
deviation:
  rule: 3
  type: blocking_issue
  description: "Added missing zod dependency"
  command: "npm install zod"
  reason: "Import fails without package"
```

### Rule 4: ASK About Architectural Changes
**Permission required.**

Stop and ask user before:
- New database tables or major schema changes
- New services or major component additions
- Changes to API contracts
- New external dependencies (beyond obvious needs)
- Authentication/authorization model changes

```yaml
deviation:
  rule: 4
  type: architectural_change
  status: PENDING_APPROVAL
  description: "Considering adding Redis for session storage"
  current: "Sessions stored in SQLite"
  proposed: "Redis for distributed session storage"
  reason: "Multiple server instances need shared sessions"
  question: "Should we add Redis, or use sticky sessions instead?"
```

---

## Decision Tree

```
Encountered unexpected issue
         │
         ▼
    Is it broken code?
    (errors, bugs, security)
         │
    YES ─┴─ NO
     │      │
     ▼      ▼
   Rule 1   Is critical functionality missing?
   Auto-fix (validation, auth, error handling)
              │
         YES ─┴─ NO
          │      │
          ▼      ▼
        Rule 2   Is it blocking task completion?
        Auto-add (deps, imports, config)
                   │
              YES ─┴─ NO
               │      │
               ▼      ▼
             Rule 3   Is it architectural?
             Auto-fix (tables, services, contracts)
                        │
                   YES ─┴─ NO
                    │      │
                    ▼      ▼
                  Rule 4   Ignore or note
                  ASK      for future
```

---

## Documentation Requirements

All deviations MUST be documented in SUMMARY.md:

```yaml
# 2-3-SUMMARY.md
phase: 2
plan: 3

deviations:
  - rule: 1
    type: bug_fix
    description: "Fixed null reference in auth service"
    location: src/services/auth.ts:45

  - rule: 2
    type: missing_critical
    description: "Added Zod validation to user API"
    location: src/api/users.ts:23-45

  - rule: 3
    type: blocking_issue
    description: "Installed missing jose dependency"
    command: "npm install jose"

  - rule: 4
    type: architectural_change
    status: APPROVED
    description: "Added refresh_tokens table"
    approved_by: user
    approved_at: 2024-01-15T10:30:00Z
```

---

## Deviation Tracking in Tasks

When a deviation is significant, create tracking:

### Minor Deviations
Log in SUMMARY.md, no separate task.

### Major Deviations (Rule 4)
Create a decision record:

```sql
INSERT INTO task_history (
  task_id,
  field,
  old_value,
  new_value,
  changed_by
) VALUES (
  'current-task-id',
  'deviation',
  NULL,
  '{"rule": 4, "description": "Added Redis", "approved": true}',
  'worker-123'
);
```

### Deviations That Spawn Work
If fixing a deviation requires substantial work:

1. Complete current task
2. Create new task for deviation work
3. Link new task as dependency if blocking
4. Continue with original plan

---

## Examples by Category

### Rule 1: Bug Fixes

| Issue | Fix | Documentation |
|-------|-----|---------------|
| Undefined property access | Add optional chaining | Note in summary |
| SQL injection vulnerability | Use parameterized query | Note + security flag |
| Race condition in async code | Add proper await | Note in summary |
| Incorrect error message | Fix message text | Note in summary |

### Rule 2: Missing Critical

| Gap | Addition | Documentation |
|-----|----------|---------------|
| No input validation | Add Zod/Yup schema | Note in summary |
| No error handling | Add try/catch + logging | Note in summary |
| No auth check | Add middleware | Note in summary |
| No CSRF token | Add csrf protection | Note + security flag |

### Rule 3: Blocking Issues

| Blocker | Resolution | Documentation |
|---------|------------|---------------|
| Missing npm package | npm install | Note in summary |
| Wrong import path | Fix path | Note in summary |
| Missing env var | Add to .env.example | Note in summary |
| TypeScript config issue | Fix tsconfig | Note in summary |

### Rule 4: Architectural (ASK FIRST)

| Change | Why Ask | Question Format |
|--------|---------|-----------------|
| New DB table | Schema is contract | "Need users_sessions table. Create it?" |
| New service | Architectural decision | "Extract auth to separate service?" |
| API contract change | Breaking change | "Change POST /users response format?" |
| New external dep | Maintenance burden | "Add Redis for caching?" |

---

## Integration with Verification

Deviations are inputs to verification:

1. **Verifier loads SUMMARY.md** with deviation list
2. **Bug fixes (Rule 1)** verify the fix doesn't break tests
3. **Critical additions (Rule 2)** verify they're properly integrated
4. **Blocking fixes (Rule 3)** verify build/tests pass
5. **Architectural changes (Rule 4)** verify they match approved design

---

## Escalation Path

If unsure which rule applies:

1. **Default to Rule 4** (ask) rather than making wrong assumption
2. Document uncertainty in deviation notes
3. Include reasoning for why you're asking

```yaml
deviation:
  rule: 4
  type: uncertain
  description: "Adding caching layer to API responses"
  reason: "Could be Rule 2 (performance is critical) or Rule 4 (new infrastructure)"
  question: "Is Redis caching appropriate here, or should we use in-memory?"
```