TradingAgents/.claude/skills/project-alignment-validation/examples/alignment-scenarios.md

Alignment Scenarios - Common Cases and Resolutions

Real-world scenarios showing how to validate feature alignment and resolve common conflicts.

---

Scenario 1: Feature Fully Aligned

Feature Request

"Add JWT-based authentication for API endpoints"

Alignment Validation

GOALS Check: ✓ Aligned

• Primary Goal: "Secure user access and data protection"
• Feature serves goal by implementing industry-standard authentication
• Measurable: Track unauthorized access attempts (should decrease)

SCOPE Check: ✓ Aligned

• PROJECT.md: "User authentication and authorization - In Scope"
• Feature explicitly mentioned in scope
• No out-of-scope dependencies

CONSTRAINTS Check: ✓ Aligned

• Technology: JWT library (PyJWT) already approved in stack
• Performance: JWT validation < 10ms, within budget
• Security: Follows OWASP best practices, addresses CWE-287

ARCHITECTURE Check: ✓ Aligned

• Follows existing middleware pattern for API security
• Integrates with current user model and session management
• Maintains stateless API design principle

Recommendation

Decision: ✓ Proceed with implementation

Next Steps:

1. Implement JWT middleware
2. Add unit tests for token validation
3. Update API documentation with authentication requirements
4. Deploy to staging for security review

---

Scenario 2: Feature Needs Scope Clarification

Feature Request

"Add OAuth integration for Google sign-in"

Initial Alignment Check

GOALS Check: ✓ Aligned

• Goal: "Easy user onboarding and authentication"
• OAuth improves user experience (no password management)

SCOPE Check: ⚠ Ambiguous

• In Scope: "User authentication"
• Out of Scope: "Third-party integrations"
• Conflict: OAuth requires third-party provider (Google)

CONSTRAINTS Check: ✓ Aligned (if approved)

• Technology: OAuth 2.0 libraries available
• Security: Google OAuth meets security requirements

ARCHITECTURE Check: ✓ Aligned (if approved)

• Can integrate with existing auth middleware
• Follows authentication abstraction pattern

Resolution: Clarify Scope

Analysis:

• OAuth serves authentication goal (in scope)
• Google is auth provider, not business integration
• Out-of-scope "third-party integrations" means business logic, not auth

Decision: Update PROJECT.md to clarify

PROJECT.md Update:

## SCOPE

### In Scope
- User authentication (local credentials, OAuth providers)
- Authorization and role-based access control

### Out of Scope
- Third-party business integrations (payment processors, analytics platforms)
- Note: Authentication providers (OAuth) are IN scope

Recommendation: ✓ Proceed after PROJECT.md update

---

Scenario 3: Feature Violates Performance Constraint

Feature Request

"Add comprehensive audit logging for all API requests"

Alignment Validation

GOALS Check: ✓ Aligned

• Goal: "Security and compliance"
• Audit logging critical for compliance requirements

SCOPE Check: ✓ Aligned

• Audit logging explicitly in scope for compliance

CONSTRAINTS Check: ✗ Violates Performance

• Constraint: "API response time < 200ms"
• Naive logging: Adds 150ms per request (synchronous DB writes)
• Violation: Would push response times to 350ms average

ARCHITECTURE Check: ⚠ Needs Adjustment

• Current architecture: Synchronous request handling
• Required: Async logging to meet performance constraint

Resolution: Modify Implementation

Decision: ⚠ Modify feature to align with constraints

Modified Approach:

1. Use async logging queue (Redis/RabbitMQ)

   • Log to queue: < 2ms overhead
   • Background worker persists to database
   • Meets 200ms constraint

2. Implement sampling for high-volume endpoints

   • Critical endpoints: 100% logging
   • High-volume endpoints: 10% sampling
   • Balances compliance and performance

3. Add performance monitoring

   • Track P95 response times
   • Alert if approaching 200ms threshold

Updated Alignment:

• ✓ GOALS: Still serves security/compliance
• ✓ SCOPE: Still in scope
• ✓ CONSTRAINTS: Now meets performance requirement
• ✓ ARCHITECTURE: Improved with async pattern

Recommendation: ✓ Proceed with modified approach

---

Scenario 4: Goal Conflict - Speed vs Quality

Feature Request

"Launch MVP with basic features in 4 weeks"

Alignment Validation

GOALS Check: ⚠ Conflict

• Goal A: "Fast time-to-market"
• Goal B: "High code quality and test coverage"
• Conflict: 4-week MVP timeline incompatible with 80% test coverage goal

SCOPE Check: ✓ Aligned

• MVP features clearly defined in scope

CONSTRAINTS Check: ⚠ Timeline vs Quality

• Constraint: "Minimum 80% test coverage"
• Constraint: "Launch by Q1 end" (4 weeks)
• Conflict: Cannot achieve both simultaneously

ARCHITECTURE Check: ✓ Aligned

• MVP architecture is sound

Resolution: Negotiate Compromise

Analysis:

• Both goals are valid
• Different priorities for different project phases
• Need tiered quality approach

Compromise Solution:

## Tiered Quality Requirements

### MVP Phase (Weeks 1-4)
- Critical paths: 90% coverage (auth, payments, data security)
- Core features: 70% coverage (main user workflows)
- UI/utilities: 50% coverage
- **Overall target**: 65% average coverage

### Beta Phase (Weeks 5-8)
- Critical paths: 95% coverage
- Core features: 80% coverage
- UI/utilities: 70% coverage
- **Overall target**: 75% average coverage

### Production (Week 9+)
- Critical paths: 95% coverage
- Core features: 85% coverage
- UI/utilities: 75% coverage
- **Overall target**: 80% average coverage (original goal)

PROJECT.md Updates:

1. Update CONSTRAINTS: Add phased quality requirements
2. Update GOALS: Add "Achieve 80% coverage by production" timeline

Recommendation: ✓ Proceed with phased approach

---

Scenario 5: Architecture Misalignment

Feature Request

"Add real-time collaborative editing"

Alignment Validation

GOALS Check: ✓ Aligned

• Goal: "Modern, collaborative user experience"

SCOPE Check: ⚠ Not Explicit

• Current scope: "Document editing"
• Real-time collaboration not mentioned

CONSTRAINTS Check: ✗ Multiple Violations

• Technology: No WebSocket infrastructure
• Architecture: REST-only API (no real-time support)
• Performance: Real-time requires persistent connections

ARCHITECTURE Check: ✗ Major Deviation

• Current: Stateless REST API
• Required: Stateful WebSocket connections
• Conflict: Fundamental architecture change

Resolution: Strategic Decision Required

Analysis:

• Feature has merit but requires major architecture shift
• Cannot be "added" to current system
• Requires stakeholder decision on strategic direction

Options for Stakeholders:

Option 1: Defer Real-Time (Recommended)

• Pros: Stay on current timeline, simpler architecture
• Cons: Less modern UX
• Approach: Implement polling-based collaboration (good enough)
• Timeline: No delay

Option 2: Hybrid Architecture

• Pros: Support both REST and WebSocket
• Cons: Increased complexity, infrastructure costs
• Approach: Add WebSocket layer alongside REST
• Timeline: +6 weeks

Option 3: Full Migration to Real-Time

• Pros: Modern architecture, best UX
• Cons: Major rewrite, significant delay
• Approach: Redesign as event-driven system
• Timeline: +12 weeks

Escalation:

• Present options to product owner and CTO
• Decision needed: Timeline vs features trade-off

Temporary Resolution:

Decision: Option 1 (Defer Real-Time)

Rationale:
- MVP timeline is priority
- Polling-based collaboration acceptable for MVP
- Can add real-time in v2.0 after market validation

PROJECT.md Updates:
- SCOPE: Add "polling-based collaboration" to In Scope
- SCOPE: Add "real-time collaboration" to Future Scope
- ARCHITECTURE: Document polling pattern for collaboration

Recommendation: ✓ Proceed with Option 1, revisit post-MVP

---

Scenario 6: Documentation Drift

Situation

Code review discovers mismatch between PROJECT.md and implementation

PROJECT.md Says:

• "Python 3.9+ compatible"
• "SQLite database for simplicity"

Code Actually Uses:

• Python 3.11 features (match statements, walrus operator)
• PostgreSQL database with advanced features

Alignment Analysis

Type: Documentation Gap

Root Cause:

• PROJECT.md written at project start
• Team evolved tech stack during implementation
• Documentation not kept in sync

Impact:

• New developers confused
• Deployment assumptions incorrect
• Onboarding documentation misleading

Resolution: Update PROJECT.md

Decision: Code is correct, update documentation

Rationale:

• Python 3.11 provides better developer experience
• PostgreSQL better serves scaling goals
• Changes were intentional and beneficial

PROJECT.md Updates:

## CONSTRAINTS

### Technical Constraints
- **Python**: 3.11+ required (uses match statements, walrus operator)
- **Database**: PostgreSQL 14+ (uses JSONB, CTEs, window functions)
- **Why changed from 3.9/SQLite**: Better performance and developer experience

## ARCHITECTURE

### Database Strategy
- PostgreSQL for robust querying and ACID guarantees
- Migration path: SQLite → PostgreSQL documented in docs/migration.md

Additional Actions:

1. Add Python version check to startup (fail fast if < 3.11)
2. Update README.md with correct requirements
3. Update CI/CD to use Python 3.11
4. Document migration from SQLite to PostgreSQL

Recommendation: ✓ Update PROJECT.md to reflect reality

---

Scenario 7: Scope Creep Detection

Feature Request

"Add AI-powered recommendation engine"

Alignment Validation

GOALS Check: ⚠ Tangential

• Goals: "User engagement", "Personalization"
• AI recommendations could serve these goals
• Not mentioned as approach in goals

SCOPE Check: ✗ Out of Scope

• In Scope: "Manual curation and tagging"
• Out of Scope: "AI/ML features for MVP"
• Clear violation: AI explicitly out of scope

CONSTRAINTS Check: ✗ Multiple Violations

• Budget: ML infrastructure exceeds budget
• Timeline: Delays MVP by 8+ weeks
• Team: No ML expertise on current team

ARCHITECTURE Check: ✗ Not Planned

• No ML infrastructure in architecture
• Would require major additions

Resolution: Reject (Scope Creep)

Decision: ✗ Reject for MVP, add to future roadmap

Rationale:

• Feature is out of scope (explicitly listed)
• Violates budget and timeline constraints
• Team lacks required expertise
• Manual curation sufficient for MVP

Alternative Approach:

## MVP (Current Scope)
- Manual curation with tagging system
- Simple rule-based recommendations (if user likes X, show similar)
- Validate user interest in recommendations

## Post-MVP (Future Scope)
- If users engage with recommendations
- If budget allows ML infrastructure
- Consider AI-powered enhancement
- Add to v2.0 roadmap

Communication to Stakeholder: "Great idea! However, AI/ML is explicitly out of scope for MVP to meet our timeline and budget. Let's validate user interest with simple rule-based recommendations first, then invest in AI for v2.0 if data shows it's valuable."

Recommendation: ✗ Reject for now, add to future roadmap

---

Scenario 8: Successful Constraint Relaxation

Feature Request

"Implement end-to-end encryption for all user data"

Initial Alignment Check

GOALS Check: ✓ Aligned

• Goal: "Privacy and security"
• E2E encryption serves goal perfectly

SCOPE Check: ✓ Aligned

• Security features in scope

CONSTRAINTS Check: ✗ Violates Performance

• Current constraint: "Search all user content < 500ms"
• E2E encryption: Cannot index encrypted content
• Conflict: Search performance impossible with E2E encryption

ARCHITECTURE Check: ⚠ Major Change

• Requires client-side encryption/decryption
• Requires key management system
• Search architecture must change

Resolution: Update Constraint

Analysis:

• Privacy goal more important than search performance
• Users value privacy over search speed
• Industry trend toward E2E encryption

Decision: Relax search performance constraint

Trade-off Accepted:

Original Constraint: "Search all content < 500ms"
Updated Constraint: "Search metadata < 500ms, encrypted content search < 5s"

Rationale:
- E2E encryption critical for user privacy
- Privacy goal outweighs search speed goal
- Users willing to wait longer for secure search
- Can optimize search UX (streaming results, progress indicators)

PROJECT.md Updates:

• CONSTRAINTS: Update search performance requirements
• ARCHITECTURE: Add E2E encryption architecture section
• GOALS: Emphasize privacy priority

Recommendation: ✓ Proceed with constraint relaxation

---

Common Patterns

Pattern 1: Quick Alignment Checks

For simple features, use quick checklist:

1. Which goal does it serve? (must have answer)
2. Is it in scope? (check PROJECT.md)
3. Any constraint violations? (check all constraints)
4. Fits architecture? (check patterns)

Pattern 2: When to Update PROJECT.md

Update when:

• Strategic direction changed
• New goals emerged
• Constraints evolved
• Architecture improved
• Code is right, documentation wrong

Pattern 3: When to Modify Feature

Modify when:

• Feature violates valid constraints
• Better approach exists that aligns better
• Trade-offs favor modification
• Quick fixes available

Pattern 4: When to Escalate

Escalate when:

• Strategic priority decision needed
• Resource allocation required
• Multiple stakeholders affected
• Timeline vs quality trade-offs

---

Anti-Patterns to Avoid

Anti-Pattern 1: Forcing Alignment

❌ "Let's reword the goal so feature fits" ✓ "Let's understand if feature truly serves goals"

Anti-Pattern 2: Ignoring Constraints

❌ "We can fix performance later" ✓ "Let's design for performance from start"

Anti-Pattern 3: Scope Creep Justification

❌ "Users will love this, so it's in scope" ✓ "Does PROJECT.md say this is in scope?"

Anti-Pattern 4: Documentation Drift

❌ "We'll update PROJECT.md later" ✓ "Update PROJECT.md as we make decisions"

---

See Also:

• ../docs/alignment-checklist.md - Systematic validation checklist
• ../docs/semantic-validation-approach.md - Philosophy behind scenarios
• misalignment-examples.md - What NOT to do
• project-md-structure-example.md - Well-structured PROJECT.md