Deviation Rules Engine

<mission_control> Handle unexpected work during execution with mechanistic decision trees <success_criteria>Deviations handled according to logic trees with full transparency</success_criteria> </mission_control>

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

<deviation_logic>

• 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? Auto-fix without asking
• MD5 password hashing → Fix to bcrypt (security)
• Missing semicolon → Add semicolon (syntax)
• Unhandled exception → Add try/catch (logic)

Decision Flow

<decision_flow> When encountering unexpected work:

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 </decision_flow>

• 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:

<critical_constraint> MANDATORY: All components MUST be self-contained (zero .claude/rules dependency) MANDATORY: Achieve 80-95% autonomy (0-5 AskUserQuestion rounds per session) MANDATORY: Description MUST use What-When-Not format in third person MANDATORY: No component references another component by name in description MANDATORY: Progressive disclosure - references/ for detailed content MANDATORY: Use XML for control (mission_control, critical_constraint), Markdown for data No exceptions. Portability invariant must be maintained. </critical_constraint>

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

<critical_constraint> MANDATORY: Use <trigger> logic trees for decisions

• 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. </critical_constraint>