commit 4687e6b0e3ba74bc57aa2d3931666bdeaefb96ca Author: Zhongwei Li Date: Sat Nov 29 18:13:03 2025 +0800 Initial commit diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..8ef1dab --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,12 @@ +{ + "name": "decision-facilitator", + "description": "Collaborative technical discussion with proactive requirements gathering", + "version": "1.0.0", + "author": { + "name": "ClaudeForge Community", + "url": "https://github.com/claudeforge/marketplace" + }, + "commands": [ + "./commands" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..d2cb3fe --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# decision-facilitator + +Collaborative technical discussion with proactive requirements gathering diff --git a/commands/discuss.md b/commands/discuss.md new file mode 100644 index 0000000..b0e9fa0 --- /dev/null +++ b/commands/discuss.md @@ -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 +``` + +**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 diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..dcce44a --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,45 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:claudeforge/marketplace:plugins/commands/decision-facilitator", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "30ea06cba6cc321dd877a412671615d9d3e1f045", + "treeHash": "a76132010fb07d68ebf8baac120912cc6fb1119a8cb4db4baf6f3bfc3ed248f6", + "generatedAt": "2025-11-28T10:15:28.427197Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "decision-facilitator", + "description": "Collaborative technical discussion with proactive requirements gathering", + "version": "1.0.0" + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "4cd9024b6db7bcd44d2a12040f1f165cfc4c018a904abd422c81abb9e7e42a57" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "332dddd4495659b1f4e4c337e1ed6db37ca0a208eac83c630d672adc6e03e4d9" + }, + { + "path": "commands/discuss.md", + "sha256": "71627cb47c78817c98d484fc5bd283b00a1de3906643509298d4e8c99dc35c5a" + } + ], + "dirSha256": "a76132010fb07d68ebf8baac120912cc6fb1119a8cb4db4baf6f3bfc3ed248f6" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file