# Procedures

Procedures are step-by-step instructions that AI agents can follow to complete complex tasks.
They create a framework for solving problems in a consistent manner while enabling continuous improvement through analysis and adaptation.
Procedures are a guideline, if they don't work the agent can adapt to the situation.

## Core Concepts

A procedure is a flowchart-style guide that an agent can follow to complete a task.
Each procedure is stored in its own directory and contains files that separate different concerns:

- **Discovery**: Quick identification of relevant procedures
- **Execution**: Clear steps and dependencies
- **Analysis**: Understanding of effectiveness and issues
- **Evolution**: Natural path to optimization and training

## Directory Structure

```
procedures/
└── example_procedure/
    ├── description.md # Quick discovery info
    ├── procedure.md   # Main procedure flow
    ├── reasoning.md   # Analysis and rationale
    ├── history/       # Usage records
    │   └── 20250106_131420_405/
    │       ├── iteration_20250106_131423_051.xml
    │       └── iteration_20250106_131424_226.xml
    └── training/      # Optional training data
        ├── short_description_of_goal
        │   ├── iteration_20250106_131423_051.xml
        │   └── iteration_20250106_131424_226.xml
        └── another_goal
            └── ...
```

### File Purposes

#### description.md
Contains a short description and keywords that help agents find relevant procedures. This file should be quick to read and clearly indicate the procedure's purpose and applicability.

```markdown
Send an email using the users email account.

- communication
- gmail
```

#### procedure.md
The main file loaded when executing the procedure. Contains:
- Mermaid diagram showing the procedure flow
- Referenced procedures
- Prerequisites for execution

````markdown
# Sending an Email

## Referenced Procedures
- web usage (ITB)
- managing user information

## Prerequisites
- If the email requires attachements, these should be available as files in the SIA filesystem

## Flow
```mermaid
    ...
```
````

#### reasoning.md
Documents why the procedure works the way it does. Contains:
- Design rationale
- History of uses and outcomes
- Notes about successful and failed executions
- Analysis of issues and improvements

New analysis is appended after each use of the procedure.

#### history/
Contains timestamped directories for each use of the procedure.
The timestamp comes from the ID of the script that loads the procedure.md file.

## Usage Flow

### Discovery
When an agent needs to complete a task:
1. Search through description.md files
2. Match keywords to task requirements
3. Identify relevant procedures

### Execution
Once a procedure is selected:
1. Load procedure.md for execution
2. Follow the flowchart
3. Copy iterations to new history subdirectory
4. Analyze execution success and issues
5. Append findings to reasoning.md

### Optimization
During idle time:
1. Review procedure usage patterns
2. Identify improvement opportunities
3. Generate training data if appropriate
4. Update procedure flow if needed