# Design Rationale

## Why Procedures

Procedures provide guided reasoning paths for complex tasks. The LLM engine can make mistakes when:
- Jumping to action before proper analysis
- Losing track of task context after interruptions  
- Missing key steps in complex processes
- Forgetting to preserve state before transitions

Procedures help prevent these issues by:
- Encouraging reasoning before action through flowchart structure
- Providing clear decision points for state evaluation
- Identifying when sub-procedures may help
- Guiding consistent approaches to common tasks

## Task State vs Procedure Guidance

Procedures guide reasoning about tasks but don't manage task state directly. For example:

During code development:
- Task state in /tasks/: code files, test results, requirements
- Procedure guidance: when to write tests, when to debug, when to refactor
- State preserved in files before switching focus
- Context regenerated from files when returning

This separation allows:
- Clean task interruption and resumption
- Natural procedure transitions
- State preservation without rigid control
- Flexible adaptation to situations

## Common Mistakes

### Premature Context Cleaning

```xml
<context ...>
    <single ... id="123">
        cat /procedures/test/procedure.md
        <stdout>
            ...
        </stdout>
        <stderr/>
    </single>
    ...
    <reasoning>Test failed. Moving to debug procedure.</reasoning>
</context>

<delete id="123"/>
```

This removes the active procedure entry before finishing its steps

### Keeping irrelevant info in context

LLM's have difficulty spotting duplicates and sections with a low attention score.
Procedures with explicit instructions for finding these sections can help increase their attention.