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.
Advanced collaboration patterns for effective engineering partnership.
New to prompting Maestro? Start with the Prompting Guide to learn essential communication techniques, then return here for advanced patterns.
Iteration and Refinement
The Challenge-Refine Cycle
Maestro’s strength emerges through iteration:
Initial Implementation → Your Challenge → Refinement → Validation → Repeat if needed
Example:
- Maestro implements caching layer
- You challenge: “This doesn’t handle Redis connection failures”
- Maestro refines: Adds circuit breaker pattern
- You validate: “Show me tests proving graceful degradation”
- Maestro demonstrates: Comprehensive test output with failure injection
When to Push Back
Push back when you see:
- Unvalidated claims (“it should work”)
- Incomplete test coverage
- Missing edge case handling
- Performance assertions without benchmarks
- Shortcuts that compromise quality
- Unclear or confusing code
How to Push Back Effectively
Ineffective: “This isn’t good enough”
Effective: “The error handling is incomplete. What happens when Redis is unavailable? Add tests that simulate connection failure and prove the system degrades gracefully.”
Ineffective: “Did you test this?”
Effective: “Run the full test suite and show me the output. Then add integration tests that verify cache invalidation works correctly.”
Managing Complex Projects
Breaking Down Large Goals
For substantial projects, decompose into phases:
Example: Building a Microservices Architecture
Phase 1: Research & Design
Research microservices patterns for Node.js applications.
Deliverables:
- Analysis of 3 viable approaches
- Recommendation with trade-off analysis
- High-level architecture diagram
- Key technology choices justified
Implement the service communication layer.
Scope:
- Service discovery
- Inter-service messaging
- Error handling and retries
- Health checks
Validation: All components tested in isolation
Implement user service following the established pattern.
Must:
- Follow architecture from Phase 1
- Use communication layer from Phase 2
- Include comprehensive tests
- Document API contracts
Multi-Session Strategies
For very large projects, consider parallel sessions:
Session A: Authentication System
- Focus: User auth, JWT, permissions
- Isolated from other work
- Can be developed independently
Session B: Database Layer
- Focus: Schema, migrations, queries
- Separate concerns
- Parallel development
Session C: Integration
- Focus: Bringing A & B together
- Clone deliverables from A & B
- Integration testing
Advantages:
- Better capacity management
- Clearer focus per session
- Easier to resume specific work streams
- Reduced context switching
Working with Existing Codebases
The Discovery Pattern
Before making changes, ensure understanding:
I want to add feature X to our codebase.
Before implementing:
1. Clone the repository
2. Explain the current architecture
3. Identify where X should integrate
4. Propose 2-3 implementation approaches
5. Recommend one with justification
Only after I approve the approach, proceed with implementation.
The Incremental Integration Pattern
For large changes to existing code:
Refactor the database layer to use connection pooling.
Approach:
1. Analyze current implementation
2. Write tests that capture existing behavior
3. Implement pooling while preserving behavior
4. Verify all original tests still pass
5. Add new tests for pooling-specific logic
6. Benchmark before/after performance
Gate: No merge until all original functionality verified
The Test-Preservation Pattern
Protect against regressions:
Add retry logic to API client.
Requirements:
- All existing tests must pass unchanged
- Add new tests only for retry behavior
- Verify backward compatibility
- No changes to public API surface
If any existing test fails, stop and explain why before proceeding.
Validation and Quality Control
The Comprehensive Validation Request
Don’t let Maestro declare success without proof:
Before claiming this is complete:
1. Run the FULL test suite (not just related tests)
2. Show me the test output
3. Run performance benchmarks
4. Compare results to baseline
5. Check for regressions
6. Verify edge cases are handled
7. Confirm error scenarios are tested
8. Show me code coverage report
The Benchmark-Driven Pattern
For performance-critical work:
Optimize the image processing pipeline.
Current performance: 2 seconds per image (measured with test_images/sample.jpg)
Process:
1. Profile current implementation
2. Identify bottlenecks with evidence
3. Propose optimizations
4. Implement changes
5. Benchmark with SAME test image
6. Show before/after comparison
Target: <500ms per image
Acceptance: Must show actual benchmark results
The Test-First Pattern
Ensure testing isn’t an afterthought:
Implement user registration.
Workflow:
1. Write comprehensive tests first (TDD style)
2. Tests should cover:
- Happy path
- Invalid inputs
- Duplicate registrations
- Database failures
- Email sending failures
3. Implement to make tests pass
4. Show me test output proving all pass
Handling Challenges and Failures
When Maestro Gets Stuck
Symptoms:
- Repeated similar errors
- Circular debugging
- No progress after multiple attempts
Your Response:
Stop. Let's reconsider the approach.
Current issue: [describe what's failing]
Options:
1. Try a different implementation strategy
2. Simplify the requirements
3. Break into smaller steps
4. Research alternative solutions
What do you recommend and why?
When Tests Fail Unexpectedly
Don’t let Maestro skip or comment out tests:
These test failures are real signals.
Do NOT:
- Skip the failing tests
- Comment them out
- Change tests to match implementation
DO:
- Understand why they fail
- Fix the implementation
- Ensure all tests pass
- Add tests if coverage is insufficient
When Requirements Aren’t Clear
Maestro can help clarify:
I want to improve the performance of our system but I'm not sure where to start.
Please:
1. Profile the current system
2. Identify the top 3 bottlenecks
3. Estimate impact of optimizing each
4. Recommend where to focus
5. Explain your reasoning
Then we'll decide together which to tackle.
Advanced Collaboration Patterns
The Specification Co-Creation Pattern
Work with Maestro to define complex features:
I want to add real-time collaboration to our document editor.
Let's work together to create a specification:
1. What are the key technical challenges?
2. What approaches exist (OT, CRDT, etc.)?
3. For each approach:
- Pros and cons
- Complexity estimate
- Library/framework options
4. Your recommendation with reasoning
After we agree on the approach, create a detailed technical specification covering architecture, data structures, conflict resolution, and testing strategy.
Only after I approve the spec, implement it.
The Competitive Analysis Pattern
Leverage Maestro for research:
Our product uses Redis for caching. Competitors claim better performance with alternatives.
Research:
1. What caching solutions are commonly used?
2. Benchmark Redis vs top 2 alternatives
3. Use our actual workload pattern for tests
4. Provide head-to-head comparison
5. Recommendation with evidence
Focus on latency, throughput, and memory efficiency.
The Systematic Refactor Pattern
For large-scale changes:
Refactor the authentication system from session-based to JWT.
Phase 1: Analysis
- Map current session implementation
- Identify all integration points
- Document dependencies
Phase 2: Test Coverage
- Ensure comprehensive tests for current behavior
- Add missing tests if needed
- Establish quality baseline
Phase 3: Implementation
- Implement JWT system
- Maintain backward compatibility during transition
- Preserve all existing test behavior
Phase 4: Migration
- Plan data migration strategy
- Implement migration scripts
- Test migration on sample data
Phase 5: Validation
- All original tests pass
- New JWT tests comprehensive
- Performance benchmarks acceptable
- Migration tested end-to-end
Only proceed to next phase after current phase validated.
Recognizing Maestro’s Limits
When to Intervene
Maestro is powerful but not omniscient. Intervene when:
Architectural Decisions: “Should we use microservices or monolith?” requires business context Maestro doesn’t have
Domain-Specific Expertise: Medical algorithms, legal compliance, financial regulations need human verification
Political/Organizational: “Which team should own this?” is outside Maestro’s scope
Subjective Preferences: UI/UX aesthetic choices where there’s no clear “correct” answer
When to Delegate
Delegate confidently when:
Well-Defined Problems: Clear requirements, measurable success criteria
Technical Implementation: Algorithm selection, data structure design, optimization strategies
Systematic Validation: Test generation, benchmark creation, edge case identification
Research and Analysis: Technical documentation review, library comparison, approach evaluation
Error Recovery Patterns
The Reset-and-Redirect Pattern
When session goes off track:
Stop. We've been debugging this for too long.
Reset:
1. Forget the last 5 turns (/forget)
2. Hide the WIP files (/hidefiles)
3. Start fresh with a simpler approach
New direction:
[describe clearer, simpler goal]
The Checkpoint-and-Branch Pattern
Before risky changes:
Before we refactor this critical system:
1. Create a checkpoint (/checkpoint)
2. Clone current state to backup branch
3. Implement refactor
4. If it fails, we restore from checkpoint
Collaborative Debugging
The Evidence-Based Debug Pattern
When something doesn’t work:
The authentication is failing but I'm not sure why.
Debug systematically:
1. Check server logs
2. Verify request format
3. Test each component in isolation
4. Identify the failing point
5. Propose fix with test that would have caught this
Show me evidence at each step.
The Hypothesis-Driven Pattern
For complex bugs:
Users report intermittent connection failures.
Scientific approach:
1. Form hypotheses for what might cause this
2. Design experiments to test each hypothesis
3. Run experiments with controlled conditions
4. Analyze results
5. Implement fix for confirmed root cause
6. Add regression tests
Document the entire investigation.
Building Long-Term Value
Documentation as You Go
As you implement this feature:
- Add inline comments for non-obvious logic
- Update README with new configuration
- Document API changes
- Add usage examples
- Update architecture diagrams if structure changed
Documentation quality is a success criterion.
Creating Maintainable Code
Implementation quality standards:
- Clear, descriptive variable/function names
- Single Responsibility Principle
- DRY (Don't Repeat Yourself)
- Comprehensive error handling
- Logging at appropriate levels
- Type hints where applicable
Code review quality is part of "done".
Knowledge Transfer
After implementing the OAuth flow:
1. Create a markdown document explaining:
- How the flow works
- Key decision points
- Security considerations
- Common pitfalls
- Debugging tips
This helps future developers (including me) maintain this code.
Measuring Session Success
Outcome-Based Metrics
Good sessions produce:
- Working, tested code
- Performance improvements with evidence
- Comprehensive documentation
- Clear understanding of systems
- Reusable knowledge
Poor sessions produce:
- Code that “should work” but isn’t tested
- Optimizations without benchmarks
- Unclear or missing documentation
- Confusion about what was actually accomplished
Quality Indicators
High-quality outcomes show:
- All tests passing
- Benchmarks meeting targets
- Edge cases explicitly handled
- Error scenarios tested
- Code follows project conventions
- Documentation is accurate and helpful
Red flags:
- Skipped or commented-out tests
- Performance claims without measurements
- Missing error handling
- Incomplete documentation
- Shortcuts taken “to save time”
Next Steps
Master these collaboration patterns:
