284 lines
6.8 KiB
Markdown
284 lines
6.8 KiB
Markdown
# Workflow Analysis Guide
|
|
|
|
This guide helps identify which operations should be Go scripts vs agent workflows.
|
|
|
|
## Decision Framework
|
|
|
|
### Ask These Questions
|
|
|
|
For each operation in your skill, evaluate:
|
|
|
|
1. **Does it require understanding/interpretation?**
|
|
- YES → Agent workflow
|
|
- NO → Continue
|
|
|
|
2. **Is the logic completely deterministic?**
|
|
- NO → Agent workflow
|
|
- YES → Continue
|
|
|
|
3. **Could it benefit from compilation/performance?**
|
|
- YES → Go script
|
|
- NO → Continue
|
|
|
|
4. **Does it need Python libraries?**
|
|
- YES → Python script
|
|
- NO → Go script
|
|
|
|
## Detailed Analysis
|
|
|
|
### Strongly Favor Go Scripts For:
|
|
|
|
**File operations:**
|
|
- Format conversions (PDF→PNG, CSV→JSON)
|
|
- Splitting/merging files
|
|
- Batch renaming/organizing
|
|
- File validation (format checks)
|
|
- Compression/decompression
|
|
|
|
**Data transformations:**
|
|
- Parsing structured data (CSV, JSON, XML)
|
|
- Format conversions with fixed rules
|
|
- Data validation against schemas
|
|
- Mathematical computations
|
|
- Text processing with regex
|
|
|
|
**Batch operations:**
|
|
- Processing thousands of files
|
|
- Parallel operations on independent items
|
|
- High-volume data processing
|
|
- Performance-critical tasks
|
|
|
|
**Binary/low-level:**
|
|
- Image manipulation (resize, crop, rotate)
|
|
- Audio/video processing
|
|
- Network protocols
|
|
- Cryptographic operations
|
|
|
|
### Strongly Favor Agent Workflows For:
|
|
|
|
**Content understanding:**
|
|
- Sentiment analysis
|
|
- Topic extraction
|
|
- Summarization
|
|
- Question answering
|
|
- Semantic search
|
|
|
|
**Decision-making:**
|
|
- Choosing strategies based on context
|
|
- Adapting to unexpected inputs
|
|
- Multi-step reasoning
|
|
- Evaluating trade-offs
|
|
|
|
**Creative tasks:**
|
|
- Writing (articles, emails, code comments)
|
|
- Design suggestions
|
|
- Naming (variables, files, projects)
|
|
- Brainstorming
|
|
|
|
**Interactive processes:**
|
|
- Troubleshooting
|
|
- Guided workflows with user input
|
|
- Adaptive error handling
|
|
- Context-dependent branching
|
|
|
|
### Consider Python Scripts For:
|
|
|
|
**Data science:**
|
|
- Pandas/NumPy operations
|
|
- Statistical analysis
|
|
- Data visualization
|
|
- Machine learning inference
|
|
|
|
**Specialized libraries:**
|
|
- Computer vision (OpenCV)
|
|
- NLP (spaCy, NLTK)
|
|
- Web scraping (BeautifulSoup)
|
|
- API clients with complex auth
|
|
|
|
**Prototyping:**
|
|
- Quick experiments
|
|
- One-off utilities
|
|
- Testing ideas before Go implementation
|
|
|
|
## Real-World Examples
|
|
|
|
### Example 1: PDF Processing Skill
|
|
|
|
**User requests:**
|
|
1. "Extract text from this PDF"
|
|
2. "Rotate all pages 90 degrees"
|
|
3. "Summarize the key points in this PDF"
|
|
4. "Split this PDF into separate pages"
|
|
|
|
**Analysis:**
|
|
|
|
| Request | Operation | Type | Reason |
|
|
|---------|-----------|------|--------|
|
|
| Extract text | pdf-extract-text | Go script | Deterministic, parsing |
|
|
| Rotate pages | pdf-rotate-pages | Go script | Deterministic, binary |
|
|
| Summarize | summarize-document | Agent workflow | Understanding required |
|
|
| Split pages | pdf-split-pages | Go script | Deterministic, file ops |
|
|
|
|
**Go scripts:** 3
|
|
**Agent workflows:** 1
|
|
|
|
### Example 2: Data Analysis Skill
|
|
|
|
**User requests:**
|
|
1. "Convert this CSV to JSON"
|
|
2. "Find outliers in this dataset"
|
|
3. "Plot the trends in this data"
|
|
4. "What insights can you find?"
|
|
|
|
**Analysis:**
|
|
|
|
| Request | Operation | Type | Reason |
|
|
|---------|-----------|------|--------|
|
|
| CSV to JSON | csv-to-json | Go script | Simple conversion |
|
|
| Find outliers | find-outliers | Python script | Statistical libraries |
|
|
| Plot trends | plot-data | Python script | Matplotlib/Seaborn |
|
|
| Find insights | analyze-insights | Agent workflow | Interpretation needed |
|
|
|
|
**Go scripts:** 1
|
|
**Python scripts:** 2
|
|
**Agent workflows:** 1
|
|
|
|
### Example 3: Code Generation Skill
|
|
|
|
**User requests:**
|
|
1. "Format this code"
|
|
2. "Generate boilerplate for a REST API"
|
|
3. "Review this code for bugs"
|
|
4. "Add error handling"
|
|
|
|
**Analysis:**
|
|
|
|
| Request | Operation | Type | Reason |
|
|
|---------|-----------|------|--------|
|
|
| Format code | format-code | Go script | Deterministic rules |
|
|
| Generate boilerplate | generate-boilerplate | Go script | Template-based |
|
|
| Review for bugs | review-code | Agent workflow | Reasoning required |
|
|
| Add error handling | add-error-handling | Agent workflow | Context-dependent |
|
|
|
|
**Go scripts:** 2
|
|
**Agent workflows:** 2
|
|
|
|
## Common Patterns
|
|
|
|
### Pattern: "Process and Analyze"
|
|
|
|
Many skills have this two-phase pattern:
|
|
|
|
1. **Process phase** (Go script)
|
|
- Extract/transform/validate data
|
|
- Fixed, deterministic operations
|
|
- Output: structured data
|
|
|
|
2. **Analyze phase** (Agent workflow)
|
|
- Interpret results
|
|
- Make recommendations
|
|
- Context-dependent decisions
|
|
|
|
**Example:**
|
|
```markdown
|
|
1. Run: scripts/bin/extract-metrics data.log
|
|
Extracts structured metrics to metrics.json
|
|
|
|
2. Analyze the metrics and identify:
|
|
- Performance bottlenecks
|
|
- Unusual patterns
|
|
- Recommended optimizations
|
|
```
|
|
|
|
### Pattern: "Validate and Act"
|
|
|
|
1. **Validate** (Go script)
|
|
- Check format/schema
|
|
- Fast, deterministic
|
|
- Output: valid/invalid + errors
|
|
|
|
2. **Act** (Agent workflow or Go script)
|
|
- If valid → Go script for fixed action
|
|
- If invalid → Agent helps troubleshoot
|
|
|
|
**Example:**
|
|
```markdown
|
|
1. Run: scripts/bin/validate-config config.yaml
|
|
- Validates against schema
|
|
- Returns validation errors
|
|
|
|
2. If valid:
|
|
- Run: scripts/bin/apply-config config.yaml
|
|
|
|
If invalid:
|
|
- Review errors and suggest fixes
|
|
```
|
|
|
|
### Pattern: "Batch with Exceptions"
|
|
|
|
1. **Batch process** (Go script)
|
|
- Process 95% of standard cases
|
|
- Fast, parallel
|
|
- Flag exceptions
|
|
|
|
2. **Handle exceptions** (Agent workflow)
|
|
- Review flagged items
|
|
- Make case-by-case decisions
|
|
- Learn patterns for future
|
|
|
|
## Anti-Patterns
|
|
|
|
### ❌ Over-Engineering
|
|
|
|
Don't create Go scripts for:
|
|
- Operations done once
|
|
- Simple 5-line operations
|
|
- Operations that may need frequent changes
|
|
|
|
**Better:** Keep as agent workflow or simple bash command
|
|
|
|
### ❌ Under-Engineering
|
|
|
|
Don't use agent workflows for:
|
|
- Operations rewritten 10+ times
|
|
- Performance-critical bottlenecks
|
|
- Operations with clear pass/fail criteria
|
|
|
|
**Better:** Extract to Go script
|
|
|
|
### ❌ Wrong Tool
|
|
|
|
Don't use Go for:
|
|
- Complex data science (use Python)
|
|
- Operations requiring heavyweight libraries
|
|
- Rapid prototyping
|
|
|
|
Don't use Python for:
|
|
- High-performance requirements
|
|
- Binary/low-level operations
|
|
- Simple file processing
|
|
|
|
## Optimization Checklist
|
|
|
|
When reviewing a skill design:
|
|
|
|
- [ ] Every Go script is truly deterministic
|
|
- [ ] Every agent workflow truly needs reasoning
|
|
- [ ] No operations rewritten 3+ times
|
|
- [ ] Performance-critical paths identified
|
|
- [ ] Python used only where libraries needed
|
|
- [ ] Clear boundaries between phases
|
|
- [ ] Error handling strategy defined
|
|
- [ ] Testing approach planned
|
|
|
|
## Next Steps
|
|
|
|
After analysis:
|
|
|
|
1. List all Go scripts to create
|
|
2. List all Python scripts to create
|
|
3. Document agent workflows in SKILL.md
|
|
4. Create integration points between scripts and workflows
|
|
5. Plan testing strategy
|
|
6. Implement in priority order
|