--- name: analyze:explain description: Explain and analyze task, event, or code without making modifications - read-only review delegates-to: autonomous-agent:orchestrator --- # Analyze-Explain Command ## Command: `/analyze:explain` **Read-only analysis and explanation** - Reviews and explains tasks, events, code, or issues without making any modifications. Perfect for understanding what needs to be done before committing to changes. **🔍 Pure Analysis Mode:** - **Zero Modifications**: Absolutely no code changes, no fixes, no commits - **Comprehensive Explanation**: Detailed breakdown of what, why, and how - **Impact Analysis**: What would change if task were implemented - **Risk Assessment**: Potential issues and concerns - **Recommendation Generation**: Suggested approaches without implementation - **Learning Integration**: Learns from analysis patterns ## How It Works 1. **Task Understanding**: Analyzes the request or code in detail 2. **Context Gathering**: Examines relevant code, files, and dependencies 3. **Impact Assessment**: Identifies what would be affected by changes 4. **Risk Analysis**: Evaluates potential problems and edge cases 5. **Approach Recommendation**: Suggests optimal implementation strategies 6. **Pattern Learning**: Stores analysis patterns for future reference ## Usage ### Basic Usage ```bash # Explain a feature request /analyze:explain "add user authentication with JWT" # Explain existing code or issue /analyze:explain "why is the login endpoint failing" # Explain error or bug /analyze:explain "investigate memory leak in data processing" # Explain architectural decision /analyze:explain "should we use microservices or monolith for this project" ``` ### With Context ```bash # Explain with specific file context /analyze:explain "how does authentication work in auth/login.py" # Explain with repository URL /analyze:explain "analyze authentication approach in https://github.com/user/repo" # Explain test failures /analyze:explain "why are these 5 tests failing in test_auth.py" # Explain performance issue /analyze:explain "what's causing slow response times in API endpoints" ``` ### Advanced Options ```bash # Detailed technical explanation /analyze:explain "explain JWT implementation" --detail-level technical # High-level overview /analyze:explain "explain authentication system" --detail-level overview # Include code examples in explanation /analyze:explain "how to implement caching" --include-examples # Compare multiple approaches /analyze:explain "Redis vs Memcached for caching" --compare-approaches ``` ## Output Format ### Terminal Output (Concise Summary) ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 🔍 ANALYSIS COMPLETE - READ-ONLY ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Task: "add user authentication with JWT" Complexity: Medium | Estimated Time: 3-4 hours | Risk Level: Medium Key Findings: * No existing authentication system detected * 8 endpoints would need protection * JWT library not in dependencies Critical Considerations: 1. Token storage strategy (localStorage vs httpOnly cookies) 2. Refresh token implementation required 3. Password hashing strategy needed Recommended Approach: 1. Install python-jose and passlib 2. Implement token generation/validation 3. Add authentication middleware 📄 Full analysis: .claude/data/reports/explain-auth-jwt-2025-10-29.md ⏱ Analysis completed in 45 seconds ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Next Steps: * Review full analysis report * Use /dev:auto "add JWT auth" to implement * Use /analyze:quality to validate after implementation ``` ### Detailed Report (.claude/data/reports/) ```markdown ======================================================= TASK ANALYSIS REPORT - READ-ONLY ======================================================= Generated: 2025-10-29 16:30:00 Task: "add user authentication with JWT" Status: ANALYSIS ONLY - NO MODIFICATIONS MADE +- Task Understanding ---------------------------------+ | Request: Implement JWT-based authentication system | | | | Requirements Breakdown: | | 1. User registration endpoint | | 2. Login endpoint with JWT token generation | | 3. Token validation middleware | | 4. Token refresh mechanism | | 5. Logout functionality (token invalidation) | | 6. Protected route implementation | | | | Technical Components: | | * JWT token generation and validation | | * Password hashing (bcrypt/argon2) | | * Token storage strategy | | * Middleware for route protection | | * Refresh token rotation | +-------------------------------------------------------+ +- Current State Analysis -----------------------------+ | Project Type: FastAPI/Flask application | | Current Auth: None detected | | | | Affected Files (would be modified): | | * main.py - Add auth middleware | | * models.py - Add User model | | * routes/auth.py - New file for auth endpoints | | * utils/security.py - New file for JWT/hashing | | * requirements.txt - Add dependencies | | | | Protected Endpoints (would need auth): | | * POST /api/users/profile | | * GET /api/users/me | | * PUT /api/users/update | | * DELETE /api/users/delete | | * GET /api/admin/* | | * [3 more endpoints] | +-------------------------------------------------------+ +- Implementation Impact ------------------------------+ | Estimated Changes: | | * Files Created: 4 new files | | * Files Modified: 6 existing files | | * Lines Added: ~450-600 lines | | * Dependencies: 3 new packages | | | | Breaking Changes: | | * All protected endpoints require auth header | | * Clients must implement token storage | | * Login flow changes for existing users | | | | Database Changes: | | * New 'users' table required | | * New 'refresh_tokens' table required | | * Migration scripts needed | +-------------------------------------------------------+ +- Risk Assessment ------------------------------------+ | Security Risks: | | * [HIGH] Token storage vulnerabilities | | * [HIGH] Password hashing strength | | * [MED] Token expiration strategy | | * [MED] Refresh token rotation | | * [LOW] CORS configuration for auth | | | | Technical Risks: | | * [MED] Breaking existing API clients | | * [MED] Token validation performance impact | | * [LOW] Database migration complexity | | | | Operational Risks: | | * [MED] User migration to new auth system | | * [LOW] Monitoring and logging requirements | +-------------------------------------------------------+ +- Recommended Approaches -----------------------------+ | Approach 1: Standard JWT (Recommended) | | +- Pros: | | | * Industry standard | | | * Well-tested libraries available | | | * Good documentation | | | * Stateless authentication | | +- Cons: | | | * Token revocation complexity | | | * Larger token size | | +- Libraries: | | | * python-jose[cryptography] | | | * passlib[bcrypt] | | | * python-multipart | | +- Estimated Time: 3-4 hours | | +- Complexity: Medium | | | | Approach 2: JWT + Redis for Token Blacklist | | +- Pros: | | | * Token revocation support | | | * Better security | | | * Session management | | +- Cons: | | | * Additional infrastructure (Redis) | | | * More complex setup | | | * Stateful authentication | | +- Estimated Time: 5-6 hours | | +- Complexity: Medium-High | | | | Approach 3: OAuth2 with JWT | | +- Pros: | | | * OAuth2 standard compliance | | | * Third-party provider support | | | * Flexible scope management | | +- Cons: | | | * More complex implementation | | | * Requires additional setup | | +- Estimated Time: 6-8 hours | | +- Complexity: High | +-------------------------------------------------------+ +- Implementation Steps (if you proceed) --------------+ | Phase 1: Setup & Dependencies (30 min) | | 1. Install required packages | | 2. Configure environment variables | | 3. Set up database models | | | | Phase 2: Core Auth Logic (90 min) | | 4. Implement password hashing utilities | | 5. Create JWT token generation | | 6. Implement token validation | | 7. Add refresh token mechanism | | | | Phase 3: Endpoints (60 min) | | 8. Create registration endpoint | | 9. Create login endpoint | | 10. Create token refresh endpoint | | 11. Create logout endpoint | | | | Phase 4: Middleware & Protection (45 min) | | 12. Implement authentication middleware | | 13. Protect existing endpoints | | 14. Add role-based access control (optional) | | | | Phase 5: Testing & Documentation (45 min) | | 15. Write unit tests | | 16. Write integration tests | | 17. Update API documentation | | 18. Add usage examples | +-------------------------------------------------------+ +- Code Examples (Reference Only) ---------------------+ | Token Generation Example: | | | | ```python | | from jose import jwt | | from datetime import datetime, timedelta | | | | def create_access_token(data: dict): | | to_encode = data.copy() | | expire = datetime.utcnow() + timedelta(minutes=15)| | to_encode.update({"exp": expire}) | | return jwt.encode(to_encode, SECRET_KEY, ALGO) | | ``` | | | | Middleware Example: | | | | ```python | | from fastapi import Depends, HTTPException | | | | async def get_current_user(token: str = Depends(...)):| | try: | | payload = jwt.decode(token, SECRET_KEY, ALGO)| | return payload.get("sub") | | except JWTError: | | raise HTTPException(401, "Invalid token") | | ``` | +-------------------------------------------------------+ +- Configuration Requirements -------------------------+ | Environment Variables Needed: | | * SECRET_KEY - JWT signing key (strong random) | | * ALGORITHM - "HS256" (default) or "RS256" | | * ACCESS_TOKEN_EXPIRE_MINUTES - 15-30 recommended | | * REFRESH_TOKEN_EXPIRE_DAYS - 7-30 recommended | | | | Database Schema: | | * users table: id, username, email, password_hash | | * refresh_tokens table: token, user_id, expires_at | +-------------------------------------------------------+ +- Testing Strategy -----------------------------------+ | Unit Tests Required: | | * Token generation with valid data | | * Token validation with valid/invalid tokens | | * Password hashing and verification | | * Token expiration handling | | | | Integration Tests Required: | | * User registration flow | | * Login and token retrieval | | * Protected endpoint access with valid token | | * Protected endpoint rejection without token | | * Token refresh flow | | * Logout and token invalidation | +-------------------------------------------------------+ +- Pattern Learning Insights --------------------------+ | Similar Tasks Found: 3 previous auth implementations | | | | Common Success Patterns: | | * Using python-jose over PyJWT (92% success rate) | | * Implementing refresh tokens from start (87%) | | * Using httpOnly cookies for tokens (84%) | | | | Common Pitfalls to Avoid: | | * Weak SECRET_KEY generation (found in 23% of cases) | | * Missing token expiration (found in 18% of cases) | | * No refresh token rotation (found in 31% of cases) | | | | Learned Optimizations: | | * Cache token validation results (15% faster) | | * Use background tasks for token cleanup | | * Implement rate limiting on auth endpoints | +-------------------------------------------------------+ +- Recommendations Summary ----------------------------+ | 1. [RECOMMENDED] Use Approach 1 (Standard JWT) | | - Best balance of simplicity and security | | - Well-documented and tested | | - 3-4 hour implementation time | | | | 2. Add refresh token mechanism from start | | - Prevents need for later refactoring | | - Better user experience | | | | 3. Use httpOnly cookies instead of localStorage | | - More secure against XSS attacks | | - Industry best practice | | | | 4. Implement rate limiting on auth endpoints | | - Prevents brute force attacks | | - Add from the start | | | | 5. Write comprehensive tests | | - Auth is security-critical | | - 90%+ coverage recommended | +-------------------------------------------------------+ ======================================================= NEXT STEPS ======================================================= Ready to Implement? * Use: /dev:auto "add JWT authentication with refresh tokens" * Review: Read this report carefully first * Prepare: Backup database before migration Need More Analysis? * Security review: /validate:security * Architecture review: /analyze:project * Compare with existing repos: /analyze:repository Questions or Concerns? * Review pattern learning insights above * Check similar implementations in patterns database * Consult team for security-critical decisions ======================================================= Analysis Time: 45 seconds Pattern Matches: 3 similar tasks Confidence Level: High (92%) Recommendation Strength: Strong NO MODIFICATIONS WERE MADE TO ANY FILES This is a read-only analysis report. ``` ## Integration with Learning System The `/analyze:explain` command integrates with pattern learning: **Learning from Analysis**: - Common task patterns and requirements - Effective explanation structures - Risk assessment accuracy - Recommendation quality - User follow-through rates **Pattern Storage**: ```json { "explain_patterns": { "task_type": "authentication_jwt", "analysis_approach": { "breakdown_depth": "detailed", "risk_assessment": "comprehensive", "approaches_compared": 3, "code_examples_included": true }, "outcome": { "user_implemented": true, "implementation_success": true, "analysis_accuracy": 0.95, "time_estimate_accuracy": 0.88 }, "reuse_count": 8, "effectiveness_score": 0.92 } } ``` ## Agent Delegation `/analyze:explain` delegates to: - **orchestrator**: Main analysis coordinator - **code-analyzer**: Code structure and impact analysis - **security-auditor**: Security risk assessment - **pattern-learning**: Similar task pattern matching ## Skills Integration Auto-loads relevant skills: - **code-analysis**: For code understanding - **pattern-learning**: For similar task identification - **security-patterns**: For security considerations - **documentation-best-practices**: For clear explanations ## Use Cases ### Before Implementation ```bash # Understand requirements before coding /analyze:explain "implement real-time notifications" # Review the analysis # Then implement: /dev:auto "implement real-time notifications" ``` ### Understanding Existing Code ```bash # Understand how something works /analyze:explain "how does the caching system work in cache.py" ``` ### Troubleshooting ```bash # Understand what's wrong before fixing /analyze:explain "why is the API returning 500 errors" # Review the analysis # Then fix: /dev:auto "fix API 500 errors" ``` ### Decision Making ```bash # Compare approaches /analyze:explain "should we use GraphQL or REST for the new API" ``` ### Learning ```bash # Learn from external repositories /analyze:explain "how does authentication work in https://github.com/fastapi/fastapi" ``` ## Best Practices ### Good Explain Requests ```bash # Specific and focused /analyze:explain "explain JWT token refresh mechanism in auth/token.py" # Clear context provided /analyze:explain "why are tests failing after adding authentication" # Decision-oriented /analyze:explain "compare WebSocket vs Server-Sent Events for real-time updates" ``` ### Poor Explain Requests ```bash # Too vague /analyze:explain "explain the code" # Too broad /analyze:explain "explain everything about the project" # Not analysis-focused /analyze:explain "fix all bugs" # Use /dev:auto instead ``` ## Output Options ### Detail Levels - **overview**: High-level summary (default) - **technical**: Detailed technical analysis - **comparison**: Compare multiple approaches - **security**: Focus on security considerations ### Include Examples ```bash # With code examples /analyze:explain "JWT implementation" --include-examples # Without code examples (faster) /analyze:explain "JWT implementation" --no-examples ``` ## Performance Metrics - **Analysis Time**: 30-90 seconds typically - **Accuracy**: 90-95% for requirement understanding - **Time Estimates**: ±20% accuracy - **Risk Identification**: 85-90% of critical risks identified --- **Version**: 1.0.0 **Integration**: Uses orchestrator, code-analyzer, security-auditor agents **Skills**: code-analysis, pattern-learning, security-patterns **Platform**: Cross-platform (Windows, Linux, Mac) **Learning**: Full integration with pattern learning system **Mode**: READ-ONLY - No modifications ever made