Initial commit
This commit is contained in:
Zhongwei Li
460
commands/discuss.md
Normal file
460
commands/discuss.md
Normal file
@@ -0,0 +1,460 @@
|
||||
---
|
||||
allowed-tools: Bash, Read, Write, Edit, Grep, Glob
|
||||
description: Facilitate technical discussions and decision-making through structured questioning and analysis
|
||||
---
|
||||
|
||||
# Decision Facilitator Command
|
||||
|
||||
Guide technical discussions and facilitate decision-making through structured analysis and collaborative problem-solving.
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
/discuss <topic_or_question>
|
||||
```
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
/discuss "Should we migrate from REST to GraphQL?"
|
||||
/discuss "Which state management library: Redux vs MobX?"
|
||||
/discuss "Microservices vs Monolith architecture"
|
||||
/discuss database indexing strategy for user search
|
||||
```
|
||||
|
||||
## What This Command Does
|
||||
|
||||
Facilitates decisions by:
|
||||
|
||||
1. **Structured Analysis**: Break down complex topics into manageable components
|
||||
2. **Multi-Perspective Exploration**: Consider technical, business, and operational angles
|
||||
3. **Trade-off Evaluation**: Compare pros/cons of different approaches
|
||||
4. **Consensus Building**: Help teams align on decisions
|
||||
5. **Documentation**: Capture decision rationale for future reference
|
||||
|
||||
## Discussion Framework
|
||||
|
||||
### Step 1: Define the Decision
|
||||
|
||||
Clarify what needs to be decided:
|
||||
|
||||
```markdown
|
||||
**Decision Topic**: Choose authentication strategy
|
||||
|
||||
**Context**:
|
||||
- Current: Session-based auth with cookies
|
||||
- Options: JWT, OAuth2, Session tokens
|
||||
- Constraints: Must support mobile apps
|
||||
|
||||
**Stakeholders**:
|
||||
- Engineering team (implementation)
|
||||
- Product team (user experience)
|
||||
- Security team (compliance)
|
||||
|
||||
**Timeline**: Decision needed by end of sprint
|
||||
```
|
||||
|
||||
### Step 2: Gather Information
|
||||
|
||||
Collect relevant facts and requirements:
|
||||
|
||||
**Technical Requirements**:
|
||||
- Performance targets (response time, throughput)
|
||||
- Scalability needs (expected user growth)
|
||||
- Integration requirements (existing systems)
|
||||
- Security standards (compliance, regulations)
|
||||
- Maintenance considerations (team expertise)
|
||||
|
||||
**Business Requirements**:
|
||||
- Budget constraints
|
||||
- Time to market
|
||||
- User experience impact
|
||||
- Competitive positioning
|
||||
- Long-term strategy
|
||||
|
||||
**Current State Assessment**:
|
||||
- What works well now?
|
||||
- What are the pain points?
|
||||
- What triggered this decision?
|
||||
- What's the cost of not changing?
|
||||
|
||||
### Step 3: Explore Options
|
||||
|
||||
Systematically evaluate alternatives:
|
||||
|
||||
```markdown
|
||||
## Option 1: JWT Authentication
|
||||
|
||||
**Pros**:
|
||||
- Stateless - scales horizontally easily
|
||||
- Works well with mobile apps and SPAs
|
||||
- Industry standard with good library support
|
||||
- No server-side session storage needed
|
||||
|
||||
**Cons**:
|
||||
- Cannot invalidate tokens before expiry
|
||||
- Token size larger than session IDs
|
||||
- Requires careful secret management
|
||||
- Refresh token strategy adds complexity
|
||||
|
||||
**Implementation Effort**: Medium (2-3 weeks)
|
||||
**Maintenance Burden**: Low
|
||||
**Team Familiarity**: High
|
||||
|
||||
## Option 2: OAuth2 with Third-Party Provider
|
||||
|
||||
**Pros**:
|
||||
- Offload auth complexity to provider
|
||||
- Users can use existing accounts (Google, GitHub)
|
||||
- Professional security team maintains it
|
||||
- Reduces our liability
|
||||
|
||||
**Cons**:
|
||||
- Vendor lock-in risk
|
||||
- Depends on external service availability
|
||||
- Users without accounts need fallback
|
||||
- Monthly costs scale with users
|
||||
|
||||
**Implementation Effort**: Low (1 week)
|
||||
**Maintenance Burden**: Very Low
|
||||
**Team Familiarity**: Medium
|
||||
```
|
||||
|
||||
### Step 4: Evaluate Trade-offs
|
||||
|
||||
Compare options across key dimensions:
|
||||
|
||||
```markdown
|
||||
| Criteria | JWT | OAuth2 | Session |
|
||||
|-------------------|------------|------------|------------|
|
||||
| Scalability | Excellent | Good | Fair |
|
||||
| Security | Good | Excellent | Good |
|
||||
| Mobile Support | Excellent | Excellent | Poor |
|
||||
| Implementation | Medium | Easy | Easy |
|
||||
| Cost | Low | Medium | Low |
|
||||
| User Experience | Good | Excellent | Good |
|
||||
| Team Expertise | High | Medium | High |
|
||||
|
||||
**Winner**: JWT - Best balance for our needs
|
||||
```
|
||||
|
||||
### Step 5: Make Recommendation
|
||||
|
||||
Provide clear recommendation with rationale:
|
||||
|
||||
```markdown
|
||||
## Recommendation: Implement JWT Authentication
|
||||
|
||||
**Decision**: Adopt JWT with refresh token rotation
|
||||
|
||||
**Rationale**:
|
||||
1. Meets mobile app requirements (stateless)
|
||||
2. Team has strong JWT experience
|
||||
3. Scalability aligns with growth projections
|
||||
4. Lower long-term costs than OAuth2 provider
|
||||
5. Maintain control over auth flow
|
||||
|
||||
**Implementation Plan**:
|
||||
- Week 1: JWT library integration and basic auth
|
||||
- Week 2: Refresh token rotation and security
|
||||
- Week 3: Testing and documentation
|
||||
- Week 4: Gradual rollout with feature flags
|
||||
|
||||
**Success Metrics**:
|
||||
- Auth response time <100ms
|
||||
- Zero security incidents in first 3 months
|
||||
- 99.9% auth service uptime
|
||||
- Team can handle auth issues independently
|
||||
|
||||
**Risks & Mitigation**:
|
||||
- Risk: Token invalidation complexity
|
||||
Mitigation: Implement short-lived access tokens (15min)
|
||||
- Risk: Secret management
|
||||
Mitigation: Use AWS Secrets Manager, rotate regularly
|
||||
```
|
||||
|
||||
## Question Frameworks
|
||||
|
||||
### For Architecture Decisions
|
||||
|
||||
```markdown
|
||||
**Scalability Questions**:
|
||||
- How many users in 1 year? 5 years?
|
||||
- What's peak vs average load?
|
||||
- Geographic distribution of users?
|
||||
- Data volume growth projections?
|
||||
|
||||
**Technical Questions**:
|
||||
- Team expertise with options?
|
||||
- Integration with existing systems?
|
||||
- Testing and debugging complexity?
|
||||
- Deployment and rollback strategy?
|
||||
|
||||
**Business Questions**:
|
||||
- Total cost of ownership?
|
||||
- Time to production?
|
||||
- Impact on user experience?
|
||||
- Competitive differentiation?
|
||||
```
|
||||
|
||||
### For Technology Selection
|
||||
|
||||
```markdown
|
||||
**Maturity Assessment**:
|
||||
- How long has it existed?
|
||||
- Production usage at scale?
|
||||
- Community size and activity?
|
||||
- Enterprise adoption examples?
|
||||
|
||||
**Ecosystem Evaluation**:
|
||||
- Library and tool availability?
|
||||
- Documentation quality?
|
||||
- Training resources available?
|
||||
- Hiring pool size?
|
||||
|
||||
**Operational Considerations**:
|
||||
- Monitoring and debugging tools?
|
||||
- Performance characteristics?
|
||||
- Security track record?
|
||||
- Upgrade path and breaking changes?
|
||||
```
|
||||
|
||||
### For Process Changes
|
||||
|
||||
```markdown
|
||||
**Current State Analysis**:
|
||||
- What's working well?
|
||||
- What are the pain points?
|
||||
- Quantify the problem (metrics)?
|
||||
- Who is most affected?
|
||||
|
||||
**Proposed Change Evaluation**:
|
||||
- What improves?
|
||||
- What might get worse?
|
||||
- Learning curve for team?
|
||||
- Reversibility if it fails?
|
||||
|
||||
**Implementation Planning**:
|
||||
- Pilot program approach?
|
||||
- Training requirements?
|
||||
- Rollout timeline?
|
||||
- Success criteria?
|
||||
```
|
||||
|
||||
## Discussion Techniques
|
||||
|
||||
### 1. Five Whys
|
||||
|
||||
Dig deeper to find root causes:
|
||||
|
||||
```
|
||||
Problem: Deployments are failing frequently
|
||||
|
||||
Why? → Tests are flaky
|
||||
Why? → Tests depend on external services
|
||||
Why? → No proper mocking in place
|
||||
Why? → Team didn't know how to mock effectively
|
||||
Why? → Lack of testing best practices documentation
|
||||
|
||||
Root Cause: Need testing standards and training
|
||||
```
|
||||
|
||||
### 2. Pre-Mortem Analysis
|
||||
|
||||
Imagine failure and work backwards:
|
||||
|
||||
```markdown
|
||||
**Scenario**: Our microservices migration failed
|
||||
|
||||
**What went wrong?**:
|
||||
- Services became too granular (over-engineered)
|
||||
- Network latency caused performance issues
|
||||
- Debugging across services was nightmare
|
||||
- Team didn't have Kubernetes expertise
|
||||
- Cost overruns from infrastructure complexity
|
||||
|
||||
**Prevention**:
|
||||
- Start with logical service boundaries
|
||||
- Measure latency in early testing
|
||||
- Invest in distributed tracing upfront
|
||||
- Training before migration starts
|
||||
- Detailed cost analysis before committing
|
||||
```
|
||||
|
||||
### 3. Decision Matrix
|
||||
|
||||
Score options systematically:
|
||||
|
||||
```markdown
|
||||
| Criteria (Weight) | Option A | Option B | Option C |
|
||||
|------------------------|----------|----------|----------|
|
||||
| Performance (30%) | 8 | 6 | 9 |
|
||||
| Cost (25%) | 7 | 9 | 5 |
|
||||
| Team Expertise (20%) | 9 | 6 | 7 |
|
||||
| Scalability (15%) | 7 | 8 | 9 |
|
||||
| Maintenance (10%) | 8 | 7 | 6 |
|
||||
|------------------------|----------|----------|----------|
|
||||
| **Weighted Score** | **7.9** | **7.1** | **7.3** |
|
||||
|
||||
Winner: Option A
|
||||
```
|
||||
|
||||
## Common Discussion Scenarios
|
||||
|
||||
### Scenario 1: Database Choice
|
||||
|
||||
```markdown
|
||||
**Question**: PostgreSQL vs MongoDB for our application?
|
||||
|
||||
**Analysis**:
|
||||
1. **Data Structure**: Mostly relational with some nested docs
|
||||
→ Advantage: PostgreSQL (JSONB handles nested data)
|
||||
|
||||
2. **Query Patterns**: Complex joins and aggregations
|
||||
→ Advantage: PostgreSQL (mature query optimizer)
|
||||
|
||||
3. **Consistency**: Financial transactions require ACID
|
||||
→ Advantage: PostgreSQL (strong ACID guarantees)
|
||||
|
||||
4. **Team Experience**: Team knows SQL well
|
||||
→ Advantage: PostgreSQL (faster development)
|
||||
|
||||
**Recommendation**: PostgreSQL with JSONB for nested data
|
||||
```
|
||||
|
||||
### Scenario 2: Monorepo vs Polyrepo
|
||||
|
||||
```markdown
|
||||
**Question**: Should we use a monorepo or separate repositories?
|
||||
|
||||
**Context**:
|
||||
- 5 related services
|
||||
- Shared component library
|
||||
- Small team (8 developers)
|
||||
|
||||
**Monorepo Benefits**:
|
||||
- Atomic changes across services
|
||||
- Easier code sharing
|
||||
- Simplified dependency management
|
||||
- Single CI/CD pipeline
|
||||
|
||||
**Polyrepo Benefits**:
|
||||
- Independent deployment cycles
|
||||
- Clearer service boundaries
|
||||
- More flexible team structure
|
||||
- Smaller repo sizes
|
||||
|
||||
**Recommendation**: Monorepo
|
||||
**Rationale**: Small team benefits from simplified coordination;
|
||||
shared components make atomic changes valuable; can split later if needed
|
||||
```
|
||||
|
||||
### Scenario 3: Testing Strategy
|
||||
|
||||
```markdown
|
||||
**Question**: How much test coverage is enough?
|
||||
|
||||
**Analysis**:
|
||||
- **Critical Paths** (payment, auth): 100% coverage
|
||||
- **Business Logic**: 90%+ coverage
|
||||
- **UI Components**: 70%+ coverage
|
||||
- **Utilities**: 95%+ coverage
|
||||
|
||||
**Strategy**:
|
||||
1. Start with critical paths (highest value)
|
||||
2. Add tests for new features (shift left)
|
||||
3. Add tests when fixing bugs (prevent regression)
|
||||
4. Track coverage trends (not absolute numbers)
|
||||
|
||||
**Success Metric**: Zero critical bugs in production for 6 months
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Time-Box Discussions
|
||||
|
||||
```markdown
|
||||
**Phase 1** (15 min): Define problem and gather context
|
||||
**Phase 2** (30 min): Explore options and trade-offs
|
||||
**Phase 3** (15 min): Make decision or identify next steps
|
||||
**Total**: 1 hour maximum
|
||||
```
|
||||
|
||||
### 2. Document Decisions
|
||||
|
||||
```markdown
|
||||
# Architecture Decision Record (ADR)
|
||||
|
||||
**Title**: ADR-001: Use JWT for Authentication
|
||||
**Date**: 2025-01-15
|
||||
**Status**: Accepted
|
||||
**Context**: Need to support mobile apps and scale horizontally
|
||||
**Decision**: Implement JWT with 15-minute access tokens
|
||||
**Consequences**: Must implement token refresh flow
|
||||
**Alternatives Considered**: OAuth2, Session tokens
|
||||
```
|
||||
|
||||
### 3. Avoid Common Pitfalls
|
||||
|
||||
- **Analysis Paralysis**: Set decision deadline
|
||||
- **Bike Shedding**: Focus on high-impact decisions
|
||||
- **Groupthink**: Encourage dissenting opinions
|
||||
- **Sunk Cost Fallacy**: Evaluate based on future, not past
|
||||
- **NIH Syndrome**: Consider proven solutions first
|
||||
|
||||
### 4. Build Consensus
|
||||
|
||||
```markdown
|
||||
**Levels of Agreement**:
|
||||
1. Strong Yes: Enthusiastically support
|
||||
2. Yes: Support the decision
|
||||
3. Neutral: Can work with it
|
||||
4. Concerns: Have reservations but won't block
|
||||
5. Block: Cannot support (veto)
|
||||
|
||||
**Threshold**: Proceed if no blocks and majority yes/strong yes
|
||||
```
|
||||
|
||||
## Output Format
|
||||
|
||||
Structure discussion results:
|
||||
|
||||
```markdown
|
||||
# Decision: [Topic]
|
||||
|
||||
## Context
|
||||
- Background information
|
||||
- Why this decision is needed
|
||||
- Constraints and requirements
|
||||
|
||||
## Options Considered
|
||||
1. Option A: [Description]
|
||||
- Pros: ...
|
||||
- Cons: ...
|
||||
2. Option B: [Description]
|
||||
- Pros: ...
|
||||
- Cons: ...
|
||||
|
||||
## Analysis
|
||||
- Key trade-offs
|
||||
- Impact assessment
|
||||
- Risk evaluation
|
||||
|
||||
## Decision
|
||||
**Chosen**: Option [X]
|
||||
**Rationale**: Clear explanation
|
||||
**Next Steps**: Action items with owners
|
||||
|
||||
## Success Criteria
|
||||
- Measurable outcomes
|
||||
- Timeline
|
||||
- Review date
|
||||
```
|
||||
|
||||
## Methodology
|
||||
|
||||
This command facilitates effective decisions through:
|
||||
- **Structured Thinking**: Systematic frameworks prevent oversights
|
||||
- **Multiple Perspectives**: Technical, business, operational views
|
||||
- **Clear Trade-offs**: Explicit pros/cons of each option
|
||||
- **Actionable Outcomes**: Decisions with clear next steps
|
||||
- **Documentation**: Captured rationale for future reference
|
||||
Reference in New Issue
Block a user