Repository navigation
03 workflows handoff patterns
Doug Beard edited this page Aug 20, 2025
·
1 revision
Effective handoff patterns ensure seamless transitions between Coherence APM personas using /switch and /handoff commands, preserving unified context, maintaining momentum, and enabling continuous progress. This workflow provides structured approaches for different types of transitions and context preservation scenarios using the actual Coherence framework capabilities.
-
Unified Context Continuity: Session notes in
.apm/session_notes/preserve information during persona transitions - Clear Accountability: Receiving persona understands exactly what they're responsible for
- Actionable Information: Handoff includes specific next steps and priorities using actual commands
- Quality Preservation: Work quality standards are maintained across transitions
-
Efficient Transitions: Minimal time lost using
/switchand/handoffcommands - Voice Notifications: Audio feedback confirms handoff completion using TTS system
- Same Persona, Different Session: Continuing work across time boundaries
- Planned Handoffs: Scheduled transitions at logical completion points
- End-of-Day Handoffs: Daily work boundary transitions
- Sequential Work: Natural progression from one persona to another
- Expertise-Based: Transitioning to persona with required specialized knowledge
- Collaborative Review: Multiple personas reviewing or validating work
- Urgent Escalation: Critical issues requiring immediate attention
- Blocking Issues: Transitions due to unexpected obstacles
- Resource Availability: Transitions due to team member availability
# Change to specific persona with context preservation
/switch analyst # Switch to analyst persona
/switch architect # Switch to architect persona
/switch qa # Switch to QA persona
/switch dev # Switch to developer personaFeatures:
- Preserves current session context
- Updates session notes automatically
- Maintains unified context engineering
- Provides voice notification of switch
# Direct transfer with seamless context handoff
/handoff developer # Hand off current work to developer
/handoff qa # Hand off for quality assurance
/handoff po # Hand off to product ownerFeatures:
- Creates explicit handoff documentation
- Transfers responsibility clearly
- Maintains work continuity
- Provides audio confirmation
All handoffs are automatically documented in:
.apm/session_notes/YYYY-MM-DD-HH-mm-ss-Persona-Handoff.md
# HANDOFF TO: [Target Persona]
**Date**: YYYY-MM-DD HH:MM:SS
**From**: [Current Persona]
**To**: [Target Persona]
**Command Used**: /switch or /handoff
## Context Preserved
- Current work state
- Session notes continuation
- Unified context maintenance
## Next Steps
- [Specific actions for receiving persona]## HANDOFF TO: [Target Persona/Person]
**Date**: YYYY-MM-DD HH:MM:SS
**From**: [Current Persona] - [Person Name if applicable]
**To**: [Target Persona] - [Person Name if applicable]
**Handoff Type**: [Temporal/Persona/Emergency]
### CURRENT STATE SUMMARY
**Work Completed**:
- [Specific accomplishments with evidence]
- [Files modified or created]
- [Decisions made and rationale]
**Work In Progress**:
- [Tasks currently 50-99% complete]
- [Expected completion timeline]
- [Any dependencies or waiting items]
**Work Not Started**:
- [Planned work that hasn't begun]
- [Priority order for remaining work]
- [Resource requirements or constraints]
### CONTEXT FOR RECEIVING PERSONA
**Background Information**:
- [Key decisions made in previous sessions]
- [Important constraints or requirements]
- [Stakeholder preferences or feedback]
- [Technical decisions and rationale]
**Current Environment State**:
- [System configuration or setup]
- [Database state or test data]
- [Development environment status]
- [Deployment or infrastructure state]
### IMMEDIATE NEXT STEPS
**Priority 1 (Must do first)**:
1. [Specific action with clear success criteria]
2. [Second priority action with timeline]
3. [Third priority action with dependencies]
**Priority 2 (Should do next)**:
1. [Important but not urgent tasks]
2. [Preparation for future work]
3. [Documentation or cleanup tasks]
**Priority 3 (Can do if time permits)**:
1. [Nice-to-have improvements]
2. [Exploration or research tasks]
3. [Technical debt reduction]
### DEPENDENCIES & BLOCKERS
**Waiting On**:
- [External dependencies with expected resolution]
- [Stakeholder decisions or approvals]
- [Resource availability or allocation]
**Known Blockers**:
- [Issues that prevent progress]
- [Potential solutions or workarounds]
- [Escalation path if needed]
### SUCCESS CRITERIA FOR RECEIVING PERSONA
**How to know you're successful**:
- [Specific, measurable success indicators]
- [Quality standards to maintain]
- [Timeline expectations]
- [Stakeholder satisfaction criteria]
### RESOURCES & REFERENCES
**Key Files**:
- [Important files with descriptions]
- [Configuration files or settings]
- [Test files or data sources]
**Documentation References**:
- [Relevant documentation sections]
- [Previous session notes to review]
- [External references or resources]
**Contact Information**:
- [People to contact for questions]
- [Escalation contacts for issues]
- [Subject matter experts for specific areas]
### HANDOFF VALIDATION
- [ ] Receiving persona has read and understood handoff
- [ ] Questions about context or next steps have been answered
- [ ] Success criteria are clear and agreed upon
- [ ] Resource access has been verified
- [ ] Timeline expectations are realistic and acceptedScenario: Development complete, ready for testing
## HANDOFF TO: QA PERSONA
**Development Status**: Feature implementation complete
### WHAT WAS BUILT
**Features Implemented**:
- User authentication with JWT tokens
- Password reset functionality
- Email verification system
- Session management and security
**Files Modified**:
- `/src/auth/auth.js` - Core authentication logic
- `/src/auth/middleware.js` - Authentication middleware
- `/src/models/user.js` - User model with auth fields
- `/tests/auth.test.js` - Unit tests (all passing)
### TESTING GUIDANCE
**Test Scenarios to Focus On**:
1. Happy path user registration and login
2. Password strength validation and error handling
3. Email verification flow end-to-end
4. Session expiration and token refresh
5. Security edge cases (SQL injection, XSS protection)
**Test Data Available**:
- Test users in development database
- Mock email service configured for testing
- Postman collection with API test cases
### ACCEPTANCE CRITERIA VALIDATION
- [ ] Users can register with email and password
- [ ] Password strength requirements enforced
- [ ] Email verification required before login
- [ ] JWT tokens expire after 15 minutes
- [ ] Refresh token rotation implemented
- [ ] Rate limiting prevents brute force attacks
### KNOWN ISSUES TO VALIDATE
- Email delivery may be slow in development environment
- Password reset tokens expire after 1 hour (by design)
- Session cleanup runs every 4 hours (may affect long-running tests)Scenario: Architecture design complete, ready for implementation
## HANDOFF TO: DEVELOPER PERSONA
**Architecture Status**: System design complete and approved
### ARCHITECTURE DECISIONS
**Technology Stack**:
- Frontend: React 18 with TypeScript
- Backend: Node.js with Express.js
- Database: PostgreSQL with Prisma ORM
- Authentication: JWT with refresh token rotation
- Deployment: Docker containers on AWS ECS
**System Architecture**:
- Microservices architecture with API Gateway
- Event-driven communication using AWS SQS
- Caching layer with Redis for session management
- CDN for static assets (AWS CloudFront)
### IMPLEMENTATION GUIDELINES
**Development Priorities**:
1. Start with core business logic API
2. Implement authentication and authorization
3. Build frontend components for core user flows
4. Add integration testing framework
5. Set up CI/CD pipeline
**Code Organization**:
- `/src/api/` - Backend API endpoints
- `/src/services/` - Business logic services
- `/src/models/` - Data models and database interaction
- `/src/frontend/` - React components and pages
- `/src/tests/` - Testing framework and test cases
### TECHNICAL CONSTRAINTS
**Performance Requirements**:
- API response times under 200ms for 95% of requests
- Support 1000 concurrent users
- 99.9% uptime requirement
**Security Requirements**:
- HTTPS only in production
- Input validation on all user inputs
- SQL injection prevention
- XSS protection headers
- CSRF token validation
### DESIGN PATTERNS TO FOLLOW
- Repository pattern for data access
- Service layer for business logic
- Middleware pattern for cross-cutting concerns
- Observer pattern for event handlingScenario: Testing found issues, returning for fixes
## HANDOFF TO: DEVELOPER PERSONA
**Testing Status**: Issues found, development fixes needed
### TEST RESULTS SUMMARY
**Tests Passed**: 47/52 test cases (90% pass rate)
**Critical Issues**: 2 (must fix before release)
**High Priority Issues**: 3 (should fix before release)
**Medium Priority Issues**: 7 (can fix in next sprint)
### CRITICAL ISSUES REQUIRING IMMEDIATE ATTENTION
**Issue 1: Authentication Bypass Vulnerability**
- **Location**: `/src/auth/middleware.js` line 23
- **Problem**: JWT token validation can be bypassed with malformed tokens
- **Impact**: Security vulnerability - users can access protected resources
- **Reproduction**: Send request with token "invalid.jwt.format"
- **Suggested Fix**: Add proper token format validation before JWT.verify()
**Issue 2: Database Connection Leak**
- **Location**: `/src/services/user-service.js` multiple locations
- **Problem**: Database connections not properly closed in error scenarios
- **Impact**: Connection pool exhaustion after ~50 errors
- **Reproduction**: Trigger validation errors in user creation
- **Suggested Fix**: Use try/finally blocks to ensure connection cleanup
### HIGH PRIORITY ISSUES
**Issue 3: Email Validation Logic Error**
- **Problem**: Email validation accepts invalid email formats
- **Test Case**: Registration with "user@" passes validation
- **Expected**: Should reject emails without domain
- **Fix Complexity**: Low - update regex pattern
### REGRESSION TESTING REQUIRED
After fixes are implemented, please re-run:
- All authentication test scenarios (critical path)
- Database stress tests (connection handling)
- Email validation test suite
- Security penetration tests
### TEST EVIDENCE AVAILABLE
- Test execution report: `/tests/reports/2025-08-10-test-run.html`
- Screenshot evidence: `/tests/evidence/`
- Performance test results: `/tests/performance/load-test-results.json`Scenario: Requirements clarification and priority updates
## HANDOFF TO: DEVELOPER PERSONA
**Requirements Status**: Requirements clarified, priorities updated
### REQUIREMENT CHANGES FROM STAKEHOLDER FEEDBACK
**New Requirements**:
1. Add "Remember Me" option to login (extends session to 30 days)
2. Include user profile picture in JWT payload for UI display
3. Add audit logging for all authentication events
**Modified Requirements**:
- Password reset emails should expire after 2 hours (was 1 hour)
- Support social login with Google and GitHub (Phase 2)
- User roles should support hierarchical permissions
**Removed Requirements**:
- Multi-factor authentication moved to Phase 3
- Advanced password policies moved to Phase 2
### UPDATED ACCEPTANCE CRITERIA
**Story: User Login Enhancement**
- [ ] Login form includes "Remember Me" checkbox
- [ ] Checking "Remember Me" extends session to 30 days
- [ ] JWT payload includes user profile picture URL
- [ ] All login attempts logged with timestamp and IP
- [ ] Failed login attempts trigger security alerts after 5 attempts
### BUSINESS CONTEXT FOR DECISIONS
**Why "Remember Me" is important**:
- 67% of users requested this feature in user research
- Reduces support tickets for password resets by ~30%
- Competitive requirement (all major competitors have this)
**Why audit logging is critical**:
- Compliance requirement for SOC2 certification
- Security team requirement for threat detection
- Executive dashboard requirement for user analytics
### PRIORITY AND TIMELINE UPDATES
**High Priority (Complete this sprint)**:
1. "Remember Me" functionality implementation
2. JWT payload enhancement for profile pictures
3. Basic audit logging framework
**Medium Priority (Next sprint)**:
1. Advanced audit reporting dashboard
2. Security alert automation
3. User role hierarchy foundation
### STAKEHOLDER COMMUNICATION NEEDS
**Demo Requirements**:
- Product demo scheduled for Friday at 2 PM
- Focus on "Remember Me" user experience
- Show audit logging in admin interface
**Questions for Next Review**:
- Should profile pictures be cached for performance?
- What's the preferred format for audit log entries?
- How should we handle users without profile pictures?Scenario: Complex work requiring multiple persona review
## HANDOFF TO: MULTIPLE PERSONAS (Architect + QA + Product Owner)
**Status**: Payment integration complete, needs multi-perspective review
### WORK COMPLETED
**Payment Integration Features**:
- Stripe payment processing integration
- Subscription management system
- Invoice generation and email delivery
- Payment failure handling and retry logic
- PCI compliance security measures
### REVIEW ASSIGNMENTS BY PERSONA
**ARCHITECT REVIEW FOCUS**:
- [ ] Verify PCI compliance architecture decisions
- [ ] Review payment data flow and security boundaries
- [ ] Validate error handling and retry mechanisms
- [ ] Check integration points and API contract adherence
**QA REVIEW FOCUS**:
- [ ] Test payment processing end-to-end scenarios
- [ ] Validate subscription lifecycle (create, modify, cancel)
- [ ] Test payment failure scenarios and error handling
- [ ] Verify invoice generation accuracy and delivery
**PRODUCT OWNER REVIEW FOCUS**:
- [ ] Validate business requirements and user experience
- [ ] Check subscription plan options and pricing accuracy
- [ ] Review invoice format and branding requirements
- [ ] Approve user communication templates for payment events
### COORDINATION REQUIREMENTS
**Review Timeline**: All reviews complete by Thursday EOD
**Coordination Meeting**: Friday 10 AM to discuss findings
**Decision Authority**: Product Owner for business decisions, Architect for technical
**Sign-off Required**: All three personas must approve before releaseScenario: Critical production issue requiring immediate attention
## EMERGENCY HANDOFF TO: SENIOR DEVELOPER + ARCHITECT
**Issue Severity**: CRITICAL - Production system down
**Time Detected**: 2025-08-10 14:23:00 UTC
**Impact**: All users unable to access application
### IMMEDIATE SITUATION
**Problem Description**:
- Database connection pool exhausted at 14:20 UTC
- Application returns 500 errors for all requests
- User authentication completely failing
- Payment processing system offline
**Systems Affected**:
- Main application server (all instances)
- User authentication service
- Payment processing service
- Admin dashboard (partially functioning)
### INVESTIGATION COMPLETED
**Root Cause Analysis**:
- Database migration script from this morning introduced N+1 query
- Query in user service creates 50+ database connections per request
- Connection pool limit of 100 connections exhausted within minutes
- No proper connection cleanup in new code
**Evidence Collected**:
- Database connection logs: `/logs/db-connections-2025-08-10.log`
- Application error logs: `/logs/app-errors-2025-08-10.log`
- Performance monitoring graphs: Grafana dashboard saved
- User impact metrics: ~2,847 users affected
### IMMEDIATE ACTIONS REQUIRED
**Priority 1 (Restore Service)**:
1. Revert database migration to previous version
2. Restart application servers to clear connection pool
3. Verify service restoration with health checks
4. Monitor connection pool usage for stability
**Priority 2 (Prevent Recurrence)**:
1. Review and fix N+1 query in user service code
2. Add connection pool monitoring and alerting
3. Implement circuit breaker pattern for database connections
4. Add database connection cleanup in finally blocks
### STAKEHOLDER COMMUNICATION
**Internal Communication**:
- Engineering team notified via Slack at 14:25 UTC
- Management team notified via phone at 14:30 UTC
- Customer support team briefed at 14:35 UTC
**External Communication**:
- Status page updated at 14:28 UTC
- Customer email notification prepared (pending service restoration)
- Social media response team standing by
### POST-INCIDENT REQUIREMENTS
**Incident Report**: Due within 24 hours of resolution
**Process Review**: Schedule within 1 week
**Code Review**: All database connection code requires review
**Monitoring Enhancement**: Implement additional alerting within 1 weekBefore Initiating Handoff:
- Work state is clearly documented
- All modified files are saved and committed
- Session notes are up to date
- Next steps are clearly defined
- Success criteria are documented
During Handoff Process:
- Receiving persona has read handoff documentation
- Questions have been asked and answered
- Context is understood and accepted
- Timeline expectations are realistic
- Resources and access are available
After Handoff Completion:
- Receiving persona has confirmed understanding
- Handoff has been documented in session notes
- Any clarifications have been captured
- Success metrics are being tracked
- Follow-up schedule is established if needed
Context Preservation Score: How well context is maintained across handoffs Handoff Efficiency: Time lost during transition process Information Completeness: Percentage of required information provided Receiving Persona Success: How successfully receiving persona can continue work
Problem: Providing too much irrelevant information without clear priorities Impact: Receiving persona overwhelmed, important information buried Solution: Structure information by priority, focus on actionable items
Problem: Assuming receiving persona has context they don't have Impact: Misunderstanding, incorrect implementation, wasted time Solution: Provide complete context, verify understanding
Problem: Not documenting current state of work accurately Impact: Receiving persona has to rediscover current state, lost progress Solution: Complete state documentation before handoff
Problem: Not defining what success looks like for receiving persona Impact: Unclear goals, misaligned expectations, suboptimal results Solution: Clear success criteria and quality standards
- Standard Templates: Use consistent handoff documentation format
- Priority-Based Information: Organize information by priority and urgency
- Action-Oriented: Focus on what receiving persona needs to do
- Context-Rich: Provide sufficient background without overwhelming
- Understanding Verification: Ensure receiving persona understands handoff
- Resource Access: Verify receiving persona has necessary access and tools
- Timeline Validation: Confirm timeline expectations are realistic
- Quality Standards: Ensure quality expectations are clear and achievable
- Handoff Retrospectives: Regular review of handoff effectiveness
- Template Evolution: Continuously improve handoff documentation templates
- Feedback Loops: Collect feedback from receiving personas on handoff quality
- Process Optimization: Streamline handoff process to reduce overhead
- Context Preservation: 95% of handoffs preserve all necessary context
- Transition Efficiency: <15 minutes average transition overhead
- Success Rate: 90% of receiving personas successfully continue work
- Quality Maintenance: Work quality consistent across persona transitions
- Handoff Frequency: Average handoffs per day/week
- Documentation Quality: Completeness and usefulness of handoff documentation
- Follow-up Requirements: Percentage of handoffs requiring additional clarification
- Stakeholder Satisfaction: Receiving persona satisfaction with handoff quality
- Session Continuity: Handoffs preserve session context across personas
- Documentation Links: Handoffs reference relevant session notes
- Progress Tracking: Handoffs maintain progress tracking across sessions
- Team Handoffs: Structured handoffs between team members
- Multi-User Context: Handoffs in team environments with multiple people
- Shared Resources: Handoffs include shared resource access and coordination
- Story Handoffs: Handoffs tied to specific backlog items and progress
- Epic Coordination: Handoffs maintain epic-level context and progress
- Sprint Transitions: Handoffs support sprint boundaries and planning
- Session Management - Maintaining context across work sessions
- Team Collaboration - Multi-user handoff patterns
- Backlog Workflow - Handoffs in context of project tracking
- Typical Project Flow - Handoffs in project lifecycle
Master handoff patterns to ensure seamless transitions, preserved context, and continuous progress across all persona changes and team interactions.