1# Common Patterns
2
3## Contents
4
5- [Degrees of freedom](#degrees-of-freedom)
6- [Template pattern](#template-pattern)
7- [Examples pattern](#examples-pattern)
8- [Conditional workflow pattern](#conditional-workflow-pattern)
9- [Workflow with checklist](#workflow-with-checklist)
10- [Feedback loops](#feedback-loops)
11- [Domain-specific organization](#domain-specific-organization)
12
13## Degrees of freedom
14
15Match 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).
16
17### High freedom (text instructions)
18
19Use when multiple approaches are valid or decisions depend on context.
20
21```markdown
22## Code review process
23
241. Analyze the code structure and organization
252. Check for potential bugs or edge cases
263. Suggest improvements for readability
274. Verify adherence to project conventions
28```
29
30### Medium freedom (pseudocode/parameterized scripts)
31
32Use when a preferred pattern exists but some variation is acceptable.
33
34````markdown
35## Generate report
36
37Use this template and customize as needed:
38
39```python
40def generate_report(data, format="markdown", include_charts=True):
41 # Process data
42 # Generate output in specified format
43```
44````
45
46### Low freedom (specific scripts)
47
48Use when operations are fragile, consistency is critical, or a specific sequence must be followed.
49
50````markdown
51## Database migration
52
53Run exactly this script:
54
55```bash
56python scripts/migrate.py --verify --backup
57```
58
59Do not modify the command or add additional flags.
60````
61
62## Template pattern
63
64Provide output format templates. Match strictness to requirements.
65
66**Strict** (API responses, data formats):
67
68````markdown
69## Report structure
70
71ALWAYS use this exact template:
72
73```markdown
74# [Title]
75
76## Executive summary
77
78[One paragraph]
79
80## Key findings
81
82- Finding 1
83- Finding 2
84```
85````
86
87**Flexible** (when adaptation is useful):
88
89````markdown
90## Report structure
91
92Sensible default format—adapt based on analysis:
93
94```markdown
95# [Title]
96
97## Executive summary
98
99## Key findings
100```
101
102Adjust sections as needed.
103````
104
105## Examples pattern
106
107Provide input/output pairs for output-quality-dependent tasks.
108
109````markdown
110## Commit message format
111
112**Example 1:**
113Input: Added user authentication with JWT tokens
114Output:
115
116```
117feat(auth): implement JWT-based authentication
118
119Add login endpoint and token validation middleware
120```
121
122**Example 2:**
123Input: Fixed bug where dates displayed incorrectly
124Output:
125
126```
127fix(reports): correct date formatting in timezone conversion
128```
129````
130
131## Conditional workflow pattern
132
133Guide through decision points:
134
135```markdown
136## Document modification
137
1381. Determine the modification type:
139
140 **Creating new content?** → Follow "Creation workflow"
141 **Editing existing?** → Follow "Editing workflow"
142
1432. Creation workflow:
144 - Use docx-js library
145 - Build from scratch
146 - Export to .docx
147
1483. Editing workflow:
149 - Unpack existing document
150 - Modify XML directly
151 - Validate after each change
152```
153
154## Workflow with checklist
155
156For complex multi-step tasks:
157
158````markdown
159## Form filling workflow
160
161Copy this checklist:
162
163```
164- [ ] Step 1: Analyze form (run analyze_form.py)
165- [ ] Step 2: Create field mapping
166- [ ] Step 3: Validate mapping
167- [ ] Step 4: Fill the form
168- [ ] Step 5: Verify output
169```
170
171**Step 1: Analyze the form**
172Run: `python scripts/analyze_form.py input.pdf`
173````
174
175## Feedback loops
176
177Run validator → fix errors → repeat. This pattern greatly improves output quality.
178
179```markdown
180## Document editing process
181
1821. Make edits to document
1832. **Validate immediately**: `python scripts/validate.py`
1843. If validation fails:
185 - Review the error message
186 - Fix the issues
187 - Validate again
1884. **Only proceed when validation passes**
189```
190
191## Domain-specific organization
192
193For skills with multiple domains, organize by domain to avoid loading irrelevant context.
194
195```
196bigquery-skill/
197├── SKILL.md
198└── reference/
199 ├── finance.md
200 ├── sales.md
201 ├── product.md
202 └── marketing.md
203```
204
205```markdown
206# SKILL.md
207
208## Available datasets
209
210**Finance**: Revenue, billing → See [reference/finance.md](reference/finance.md)
211**Sales**: Pipeline, accounts → See [reference/sales.md](reference/sales.md)
212```
213
214When user asks about revenue, the agent reads only finance.md.