> ## Documentation Index
> Fetch the complete documentation index at: https://docs.igent.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Session strategies

Proven patterns for different project types and goals.

## Choosing the Right Approach

Different projects benefit from different session strategies. This guide helps you choose and execute effectively.

## Greenfield Projects

### Starting from Scratch

**Characteristics**:

* No existing codebase
* Clear requirements
* Freedom in technology choices
* High autonomy potential

**Recommended strategy**:

```
Phase 1: Research and Design (30-60 minutes)
"Research best practices for [project type]. Recommend tech stack with justification."

Phase 2: Architecture (30-60 minutes)
"Create technical specification covering:
- System architecture
- Data models
- API design
- Technology choices
- Testing strategy"

Phase 3: Implementation (2-8 hours)
"Implement the specification with comprehensive tests and documentation."

Phase 4: Validation (1-2 hours)
"Run all tests, benchmark performance, verify all requirements met."
```

**Example: Building a REST API**:

```
Session goal: Build rate-limited REST API for user management

Turn 1: Research
"Research Node.js vs Python vs Go for REST APIs handling 10k requests/sec. Recommend based on our team's experience (primarily Python)."

Turn 2: Specification
"Create detailed spec for user management API with JWT auth, rate limiting, and PostgreSQL. Include data models, endpoints, and testing requirements."

Turn 3-5: Implementation
"Implement the spec. Create all files, tests, and documentation."

Turn 6: Validation
"Run all tests, benchmark under load, verify rate limiting works. Show evidence."

Turn 7: Packaging
"Create deployment documentation and /download-all for deployment team."
```

## Existing Codebases

### Understanding First

**Critical**: Don't modify before understanding.

**Discovery pattern**:

```
Session start:
"Clone github.com/org/existing-project branch develop"

Understanding phase (1-3 turns):
"Walk me through:
1. Overall architecture
2. How authentication works
3. Where business logic lives
4. Test structure and coverage
5. Dependencies and integrations"

Only after thorough understanding:
"Now implement [feature] following established patterns."
```

### Feature Addition Strategy

**For well-tested codebases**:

```
Turn 1: Clone and understand
Turn 2: Identify integration points
Turn 3: Design feature following existing patterns
Turn 4: Implement with tests
Turn 5: Verify existing tests still pass
Turn 6: Create PR
```

**For poorly-tested codebases**:

```
Additional phase: Test creation
"Before implementing the feature, create comprehensive tests for the code we'll modify. This establishes baseline behavior."

Then proceed with feature implementation.
```

## Research and Analysis Sessions

### Competitive Analysis

**Goal**: Understand landscape and make informed decisions

**Structure**:

```
Turn 1: Broad research
"Research current state-of-the-art for [domain]. Identify top 3 approaches with evidence."

Turn 2: Deep dive
"For each approach, analyze:
- Technical implementation
- Performance characteristics
- Adoption and maturity
- Pros and cons"

Turn 3: Hands-on evaluation
"Implement small prototypes of top 2 approaches. Benchmark head-to-head with our workload."

Turn 4: Recommendation
"Based on evidence, recommend approach with full justification."
```

**Example: Cache selection**:

```
"We need caching for user profile API currently hitting database.

Research caching solutions (Redis, Memcached, in-memory). For top 2:
1. Implement prototype integration
2. Benchmark with our traffic pattern
3. Test failure scenarios
4. Compare operational complexity

Recommend solution with data supporting decision."
```

### Technical Due Diligence

**Before adopting library/framework**:

```
"Evaluate [library] for our use case:
- Review documentation quality
- Check maintenance and community
- Analyze performance benchmarks
- Test integration with our stack
- Identify potential issues
- Compare to alternatives"
```

## Migration Projects

### System Migration Strategy

**Large-scale migrations** benefit from phased approach:

**Phase 1: Assessment**

```
"Analyze current [old system] implementation:
- Identify all dependencies
- Document current behavior
- Create comprehensive test coverage for existing functionality"
```

**Phase 2: Parallel Implementation**

```
"Implement [new system] alongside existing:
- Don't remove old code yet
- New implementation independent
- Comprehensive tests for new system"
```

**Phase 3: Integration**

```
"Create feature flag system:
- Allow switching between old and new
- Gradual rollout capability
- Rollback if issues discovered"
```

**Phase 4: Validation**

```
"Validate new system:
- All original tests pass
- Performance meets or exceeds old system
- No regressions in functionality"
```

**Phase 5: Cutover**

```
"Remove old implementation:
- Delete deprecated code
- Update documentation
- Remove feature flags
- Clean up"
```

### Database Migration Example

```
Migrating from MySQL to PostgreSQL:

Session 1: Preparation
- Clone repository
- Document current schema
- Identify all queries
- Create test dataset

Session 2: Schema migration
- Convert schema to PostgreSQL
- Create migration scripts
- Test with sample data

Session 3: Code migration
- Update all queries
- Handle PostgreSQL-specific syntax
- Migrate transactions and locks

Session 4: Validation
- Run full test suite
- Benchmark performance
- Verify data integrity
- Test edge cases

Session 5: Deployment
- Create deployment runbook
- Document rollback procedure
- Package migration artifacts
```

## Performance Optimization Sessions

### Systematic Optimization

**Structure**:

```
Turn 1: Baseline
"Profile current implementation. Create performance baseline with specific metrics."

Turn 2: Analysis
"Identify bottlenecks with evidence. Explain why each is a bottleneck."

Turn 3: Hypothesis
"For top 3 bottlenecks, propose optimizations with expected impact."

Turn 4: Implementation
"Implement optimizations one at a time. Benchmark after each."

Turn 5: Validation
"Run full benchmark suite. Compare to baseline. Verify no regressions."
```

**Key principles**:

* Always establish baseline first
* Change one thing at a time
* Measure after each change
* Prove improvements with data

### Example: API Performance

```
Current: API responds in 500ms average

Goal: Reduce to <100ms

Workflow:
1. "Profile the API with realistic load. Identify bottlenecks."
   
   Result: Database queries taking 450ms

2. "Analyze the queries. What makes them slow?"
   
   Result: N+1 query pattern in user relationship loading

3. "Implement query optimization using JOIN. Benchmark before/after."
   
   Result: Queries now 50ms

4. "Add Redis caching for user profile data. Benchmark with cache enabled."
   
   Result: Cache hits <10ms

5. "Run full benchmark. Compare to baseline. Show improvements."
   
   Result: 500ms → 45ms average (90% improvement)
```

## Debugging Sessions

### Bug Investigation Pattern

**Systematic debugging**:

```
Bug report: Users can't log in intermittently

Turn 1: Reproduce
"Set up test environment. Attempt to reproduce the intermittent login failure."

Turn 2: Gather evidence
"Check:
- Server logs for errors
- Database connection status
- Authentication flow
- Network issues
- Resource constraints"

Turn 3: Hypotheses
"Based on evidence, form hypotheses for root cause. List in order of likelihood."

Turn 4: Test hypotheses
"Test each hypothesis systematically. Show results."

Turn 5: Fix
"Implement fix for confirmed root cause. Add regression test."

Turn 6: Validate
"Verify:
- Bug no longer reproduces
- Regression test catches it
- No new bugs introduced"
```

### Root Cause Analysis

**For complex issues**:

```
"Production outage: API returning 500 errors

Systematic investigation:
1. Review error logs (time range: incident period)
2. Check dependency health
3. Analyze traffic patterns
4. Review recent deploys
5. Identify correlation

Present findings with timeline and evidence.
Then propose fix with validation plan."
```

## Multi-Session Strategies

### Parallel Development

**Independent features**:

```
Session A: User authentication
Session B: Payment processing  
Session C: Email notifications

Benefits:
- Work proceeds in parallel
- Better capacity management per session
- Clearer focus
- Independent PRs

Integration session later to connect pieces.
```

### Serial Deep Work

**Complex, dependent features**:

```
Session 1: Foundation (2-4 hours)
- Core data models
- Database schema
- Basic API structure

Session 2: Business Logic (3-6 hours)
- Implement core features
- Business rules
- Validation logic

Session 3: Integration (2-4 hours)
- Connect to external services
- Add monitoring
- Error handling

Session 4: Polish (1-2 hours)
- Performance optimization
- Documentation
- Final validation
```

## Domain-Specific Strategies

### Machine Learning Projects

**Pattern**:

```
Session 1: Data pipeline
- Data loading and preprocessing
- Feature engineering
- Validation and splitting

Session 2: Model development
- Model architecture
- Training loop
- Hyperparameter tuning

Session 3: Evaluation
- Metrics implementation
- Validation on test set
- Performance analysis

Session 4: Production readiness
- Model serialization
- Inference API
- Monitoring and logging
```

### Distributed Systems

**Pattern**:

```
Session 1: Service definition
- API contracts
- Data models
- Communication protocols

Session 2: Core service
- Implement primary service
- Unit tests
- Integration tests

Session 3: Secondary services
- Implement dependent services
- Inter-service communication
- Error handling

Session 4: System integration
- End-to-end testing
- Performance under load
- Failure mode analysis
```

### Data Engineering

**Pattern**:

```
Session 1: Pipeline design
- Data sources
- Transformation requirements
- Output specifications

Session 2: ETL implementation
- Extract logic
- Transform logic
- Load logic
- Error handling

Session 3: Data quality
- Validation rules
- Quality metrics
- Monitoring

Session 4: Orchestration
- Scheduling
- Retry logic
- Alerting
```

## Session Maintenance

### Regular Maintenance Tasks

**Weekly pattern**:

```
Monday: Plan week's features with Maestro
Tuesday-Thursday: Implementation sessions
Friday: Code review and quality session
- Run all tests
- Code coverage review
- Performance benchmarks
- Documentation updates
```

### Refactoring Sessions

**Dedicated refactoring**:

```
Not: "Implement feature X and also refactor Y"

Better:
Session 1: Implement feature X (focused)
Session 2: Refactor Y (separate, focused)

Advantage:
- Clear success criteria per session
- Easier to validate
- Less cognitive load
- Better capacity management
```

## Anti-Patterns to Avoid

### The Everything Session

**Don't**:

```
Single session trying to:
- Implement 5 features
- Refactor 10 files
- Fix 20 bugs
- Update all documentation
- Optimize performance
```

**Do**: Break into focused sessions per goal.

### The Scope-Creep Session

**Don't**:

```
Start: "Implement login"
Midway: "Also add OAuth"
Later: "And social login"
End: "Plus 2FA and password recovery"
```

**Do**: Complete initial scope, then expand in next session.

### The Validation-Light Session

**Don't**:

```
Implement feature → "Looks good" → Create PR

No tests run, no benchmarks, no validation
```

**Do**: Systematic validation is not optional.

### The Assumption Session

**Don't**:

```
"This probably works"
"Tests should pass"
"Performance is likely fine"
```

**Do**: Evidence, not assumptions. Always validate.

## Measuring Session Effectiveness

### Good Session Indicators

* Clear goal achieved
* All tests passing
* Performance validated with benchmarks
* Documentation updated
* Code follows project conventions
* Ready for PR or delivery

### Red Flags

* Unclear what was accomplished
* Tests failing or not run
* Performance claims without proof
* Undocumented changes
* "Works on my machine" mentality

### Post-Session Checklist

After significant session:

* [ ] Run full test suite
* [ ] Review all file changes
* [ ] Verify documentation updated
* [ ] Check performance if relevant
* [ ] Validate against success criteria
* [ ] Clean up WIP/debug code
* [ ] Create PR or package deliverables

## Next Steps

Apply these strategies:

* **[Advanced Features](getting-started/advanced-features)**: Interactive prompts, multi-client, advanced memory
* **[Integrations & Credentials](getting-started/integrations-secrets)**: External service integration
* **[Troubleshooting](../reference/troubleshooting)**: Common issues and solutions
* **[FAQ](../reference/faq)**: Frequently asked questions