Deviation Rules

Deviation Rules Engine

Automatic handling of discovered work during plan execution with clear rules and full transparency.

What This Skill Does

Apply deviation rules when encountering unexpected work during plan execution:

1. Auto-fix bugs - Fix bugs discovered during implementation
2. Add missing critical - Add critical functionality that was overlooked
3. Fix blockers - Resolve blocking issues preventing completion
4. Ask about architectural changes - Stop and ask for major structural changes
5. Log enhancements - Log non-critical improvements for later

Key Innovation: Handle real-world complexity automatically while maintaining full transparency.

Logic Trees: Mechanistic Decision Making

• Is this a logic error, syntax error, type error, security vulnerability, or performance issue?
• Is the fix unambiguous (clear solution exists)?
• Does the fix not change architecture?
• MD5 password hashing → Fix to bcrypt (security)
• Missing semicolon → Add semicolon (syntax)
• Unhandled exception → Add try/catch (logic)

Decision Flow

1. Classify: What type of deviation is this?

   • Bug? → Trigger: bug
   • Missing critical? → Trigger: missing_critical
   • Blocker? → Trigger: blocker
   • Architecture change? → Trigger: architecture_change
   • Enhancement? → Trigger: enhancement

2. Apply trigger rules:

   • If bug: Auto-fix
   • If missing_critical: Add
   • If blocker: Fix
   • If architecture_change: STOP and ask
   • If enhancement: Log and continue

3. Report action: Always explain what you did and why

• Modifying system boundaries
• Changing patterns or frameworks
• Altering deployment architecture

When to apply:

• Change affects system structure
• Change has multiple valid approaches
• Change would require updating other components
• Change conflicts with existing patterns

Example:

Plan: "Add user preferences"
Discovery: Current data model doesn't support user-specific settings
Action: STOP and ask user about data model approach
Reason: Architectural decision, multiple valid options

Recognition: "Does this change the system structure or have multiple valid approaches?"

Rule 5: Log Enhancements

Definition: Log non-critical improvements for later consideration.

What counts as enhancements:

• Code refactoring for clarity
• Adding convenience features
• Performance optimizations (non-critical)
• Documentation improvements
• Test coverage expansions

When to apply:

• Improvement is valuable but not essential
• Enhancement doesn't block current work
• Can be deferred without impact

Example:

Plan: "Add payment processing"
Discovery: Error messages could be more user-friendly
Action: Log to SUMMARY.md as enhancement
Reason: Nice to have, not essential for completion

Recognition: "Is this valuable but not essential for current task?"

SUMMARY.md Documentation

All deviations are documented in SUMMARY.md:

# Execution Summary

## Original Plan

[Original plan description]

## Deviations Log

### Auto-Fixed Bugs

- [Bug description] → [Fix applied]
- [Bug description] → [Fix applied]

### Added Missing Critical

- [Missing functionality] → [What was added]

### Fixed Blockers

- [Blocker] → [Resolution]

### Logged Enhancements

- [Enhancement idea] (deferred)
- [Enhancement idea] (deferred)

## Architectural Decisions

[Only if Rule 4 was triggered]

- [Decision point] → [User's decision]

Recognition: "Is every deviation documented for transparency?"

Application Workflow

During Execution

When encountering unexpected work:

Rule1 --> Doc[Document in SUMMARY.md]
Rule2 --> Doc
Rule3 --> Doc
Rule4 --> Wait[Wait for Decision]
Rule5 --> Doc

Doc --> Continue[Continue Execution]
Wait --> Continue

1. Classify the deviation type

2. Apply the appropriate rule

   • Execute the rule's action
   • Document in SUMMARY.md
   • Continue execution (or wait for user if Rule 4)

3. Continue with plan

   • Return to planned work
   • Update task status if needed

Example Execution

Original Plan: Add JWT authentication to API

During Implementation:
1. Discovery: Password hashing uses MD5
   → Rule 1 (Bug): Fix to bcrypt
   → Document: Fixed insecure MD5 hashing

2. Discovery: No error handling for database failures
   → Rule 2 (Missing Critical): Add error handling
   → Document: Added error handling for database operations

3. Discovery: User model doesn't have email field
   → Rule 4 (Architectural): STOP and ask user
   → Wait for user decision on data model

4. Discovery: Token expiration check could be more efficient
   → Rule 5 (Enhancement): Log for later
   → Document: Deferred: Optimize token validation

Result: Authentication complete with documented deviations

Recognition Questions

Before applying any rule, ask:

Rule 1 (Bugs):

• "Is this a bug with a clear, unambiguous fix?"
• "Does the fix preserve the intended architecture?"

Rule 2 (Missing Critical):

• "Is this essential for functionality?"
• "Was this clearly overlooked, not a new feature?"
• "Is the implementation straightforward?"

Rule 3 (Blockers):

• "Does this block progress?"
• "Is there an unambiguous resolution?"

Rule 4 (Architectural):

• "Does this change system structure?"
• "Are there multiple valid approaches?"
• "Would other components be affected?"

Rule 5 (Enhancements):

• "Is this valuable but not essential?"
• "Can this be deferred without impact?"

Best Practices

Transparency

• Document EVERY deviation in SUMMARY.md
• Explain WHY each deviation was necessary
• Note what was done vs what was planned

Judgement

• Be conservative with Rule 4 (when in doubt, ask)
• Be generous with Rule 2 (err on side of completeness)
• Be honest with Rule 5 (log real improvements, don't ignore)

Context

• Consider project size and complexity
• Consider team practices and standards
• Consider long-term maintenance impact

Common Mistakes

❌ Wrong: Treating every unexpected item as architectural (Rule 4) ✅ Correct: Only Rule 4 for structural changes with multiple valid approaches

❌ Wrong: Ignoring enhancements because they're not in the plan ✅ Correct: Log enhancements (Rule 5) for future consideration

❌ Wrong: Not documenting deviations ✅ Correct: Always document to SUMMARY.md for transparency

❌ Wrong: Making architectural assumptions without asking ✅ Correct: Rule 4 triggers user consultation for architecture decisions

Integration with Planning

Related Skills

This skill integrates with:

• engineering-lifecycle - Test-driven development with deviation handling
• invocable-development - Component creation with automatic fixes
• /orchestrate - Native orchestration with deviation rules

Arguments

This skill is loaded automatically during plan execution. No direct invocation needed.

Manual invocation (for reference/testing):

Skill: deviation-rules
Args: [deviation description] [rule to apply]

Example Use Cases

Use Case 1: API Development

Plan: "Add user profile endpoint"
Deviation 1: No input validation → Rule 2 (add validation)
Deviation 2: Database query vulnerable to SQL injection → Rule 1 (fix bug)
Deviation 3: Response format inconsistent → Rule 4 (ask about standard)

Use Case 2: Frontend Component

Plan: "Create dashboard widget"
Deviation 1: Missing loading state → Rule 2 (add critical)
Deviation 2: Could use animations → Rule 5 (log enhancement)
Deviation 3: Color system doesn't support theme → Rule 4 (ask about theming)

Use Case 3: Infrastructure

Plan: "Set up CI/CD pipeline"
Deviation 1: Docker build fails → Rule 3 (fix blocker)
Deviation 2: No test coverage reporting → Rule 2 (add critical)
Deviation 3: Could add deployment previews → Rule 5 (log enhancement)

Trust intelligence - Deviation rules enable automatic handling of real-world complexity while maintaining transparency and architectural integrity.

Genetic Code

This component carries essential Seed System principles for context: fork isolation:

Delta Standard: Good Component = Expert Knowledge − What Claude Already Knows

Recognition Questions:

• "Would Claude know this without being told?" → Delete (zero delta)
• "Can this work standalone?" → Fix if no (non-self-sufficient)
• "Did I read the actual file, or just see it in grep?" → Verify before claiming

• Classify deviation type using trigger conditions
• Apply mechanistic rules based on trigger
• Never make interpretive decisions
• Follow decision flow exactly

MANDATORY: Document every deviation

• Auto-fixes: Log bug and fix applied
• Additions: Log what was added and why
• Architectural: Document user decision
• Enhancements: Log for later consideration

MANDATORY: Be conservative with architectural triggers

• Only use Rule 4 for structural changes
• Multiple valid approaches = ask user
• When in doubt, ask rather than assume
• Never change architecture without explicit approval

MANDATORY: Be generous with missing critical

• Err on side of completeness
• Add what's clearly overlooked
• Don't ask for obvious essentials
• Implementation must be functional

MANDATORY: Stop and ask for architectural changes

• File/folder structure changes
• Major component additions/removals
• Data model or schema changes
• Pattern or framework changes

No exceptions. Logic trees make decisions mechanistic, not interpretive.