# Common Patterns

## Contents

- [Degrees of freedom](#degrees-of-freedom)
- [Template pattern](#template-pattern)
- [Examples pattern](#examples-pattern)
- [Conditional workflow pattern](#conditional-workflow-pattern)
- [Workflow with checklist](#workflow-with-checklist)
- [Feedback loops](#feedback-loops)
- [Domain-specific organization](#domain-specific-organization)

## Degrees of freedom

Match specificity to task fragility. Think of an agent exploring a path: a narrow bridge with cliffs needs specific guardrails (low freedom), while an open field allows many routes (high freedom).

### High freedom (text instructions)

Use when multiple approaches are valid or decisions depend on context.

```markdown
## Code review process

1. Analyze the code structure and organization
2. Check for potential bugs or edge cases
3. Suggest improvements for readability
4. Verify adherence to project conventions
```

### Medium freedom (pseudocode/parameterized scripts)

Use when a preferred pattern exists but some variation is acceptable.

````markdown
## Generate report

Use this template and customize as needed:

```python
def generate_report(data, format="markdown", include_charts=True):
    # Process data
    # Generate output in specified format
```
````

### Low freedom (specific scripts)

Use when operations are fragile, consistency is critical, or a specific sequence must be followed.

````markdown
## Database migration

Run exactly this script:

```bash
python scripts/migrate.py --verify --backup
```

Do not modify the command or add additional flags.
````

## Template pattern

Provide output format templates. Match strictness to requirements.

**Strict** (API responses, data formats):

````markdown
## Report structure

ALWAYS use this exact template:

```markdown
# [Title]

## Executive summary

[One paragraph]

## Key findings

- Finding 1
- Finding 2
```
````

**Flexible** (when adaptation is useful):

````markdown
## Report structure

Sensible default format—adapt based on analysis:

```markdown
# [Title]

## Executive summary

## Key findings
```

Adjust sections as needed.
````

## Examples pattern

Provide input/output pairs for output-quality-dependent tasks.

````markdown
## Commit message format

**Example 1:**
Input: Added user authentication with JWT tokens
Output:

```
feat(auth): implement JWT-based authentication

Add login endpoint and token validation middleware
```

**Example 2:**
Input: Fixed bug where dates displayed incorrectly
Output:

```
fix(reports): correct date formatting in timezone conversion
```
````

## Conditional workflow pattern

Guide through decision points:

```markdown
## Document modification

1. Determine the modification type:

   **Creating new content?** → Follow "Creation workflow"
   **Editing existing?** → Follow "Editing workflow"

2. Creation workflow:
   - Use docx-js library
   - Build from scratch
   - Export to .docx

3. Editing workflow:
   - Unpack existing document
   - Modify XML directly
   - Validate after each change
```

## Workflow with checklist

For complex multi-step tasks:

````markdown
## Form filling workflow

Copy this checklist:

```
- [ ] Step 1: Analyze form (run analyze_form.py)
- [ ] Step 2: Create field mapping
- [ ] Step 3: Validate mapping
- [ ] Step 4: Fill the form
- [ ] Step 5: Verify output
```

**Step 1: Analyze the form**
Run: `python scripts/analyze_form.py input.pdf`
````

## Feedback loops

Run validator → fix errors → repeat. This pattern greatly improves output quality.

```markdown
## Document editing process

1. Make edits to document
2. **Validate immediately**: `python scripts/validate.py`
3. If validation fails:
   - Review the error message
   - Fix the issues
   - Validate again
4. **Only proceed when validation passes**
```

## Domain-specific organization

For skills with multiple domains, organize by domain to avoid loading irrelevant context.

```
bigquery-skill/
├── SKILL.md
└── reference/
    ├── finance.md
    ├── sales.md
    ├── product.md
    └── marketing.md
```

```markdown
# SKILL.md

## Available datasets

**Finance**: Revenue, billing → See [reference/finance.md](reference/finance.md)
**Sales**: Pipeline, accounts → See [reference/sales.md](reference/sales.md)
```

When user asks about revenue, the agent reads only finance.md.