669 lines
19 KiB
Markdown
669 lines
19 KiB
Markdown
# /sdd:story-patterns
|
|
|
|
## Meta
|
|
- Version: 2.0
|
|
- Category: story-analysis
|
|
- Complexity: high
|
|
- Purpose: Identify recurring patterns in completed stories to extract reusable knowledge and improve processes
|
|
|
|
## Definition
|
|
**Purpose**: Analyze completed stories to discover technical patterns, common problems, success strategies, code reusability opportunities, and anti-patterns.
|
|
|
|
**Syntax**: `/sdd:story-patterns [category]`
|
|
|
|
## Parameters
|
|
| Parameter | Type | Required | Default | Description | Validation |
|
|
|-----------|------|----------|---------|-------------|------------|
|
|
| category | string | No | "all" | Pattern category to analyze (technical, problems, success, code, process, all) | One of: technical, problems, success, code, process, all |
|
|
|
|
## INSTRUCTION: Analyze Story Patterns
|
|
|
|
### INPUTS
|
|
- category: Optional pattern category filter (defaults to all)
|
|
- Completed story files from `/docs/stories/completed/`
|
|
- Optional: Stories from other stages for trend analysis
|
|
|
|
### PROCESS
|
|
|
|
#### Phase 1: Story Data Collection
|
|
1. **SCAN** `/docs/stories/completed/` directory for all `.md` files
|
|
2. **PARSE** each story file to extract:
|
|
- Implementation approach (from Technical Notes)
|
|
- Technologies used (from Stack)
|
|
- Problems encountered (from Progress Log)
|
|
- Solutions applied (from Progress Log)
|
|
- Success criteria and outcomes
|
|
- Test cases and results
|
|
- Code patterns (from Implementation Checklist)
|
|
- Dependencies and integrations
|
|
- Lessons learned
|
|
|
|
3. **CATEGORIZE** extracted data by type:
|
|
- Technical implementations
|
|
- Problem/solution pairs
|
|
- Success factors
|
|
- Code structures
|
|
- Process workflows
|
|
|
|
4. **FILTER** by category if specified
|
|
|
|
#### Phase 2: Technical Pattern Analysis
|
|
1. **IDENTIFY** common implementation approaches:
|
|
- Group stories by similar technical solutions
|
|
- Count frequency of each approach
|
|
- Extract specific examples
|
|
|
|
2. **DETECT** recurring architectures:
|
|
- Design patterns (MVC, Repository, etc.)
|
|
- Integration patterns (API, Queue, Event)
|
|
- Data patterns (Migration, Seeding, etc.)
|
|
|
|
3. **ANALYZE** technology combinations:
|
|
- Frequently paired technologies
|
|
- Successful tech stack patterns
|
|
|
|
4. **DISPLAY** technical patterns:
|
|
```
|
|
🔧 TECHNICAL PATTERNS FOUND
|
|
══════════════════════════════════
|
|
|
|
Common Implementations:
|
|
|
|
Pattern: JWT Authentication with Refresh Tokens
|
|
- Used in: [X] stories ([STORY-IDs])
|
|
- Success rate: [X]%
|
|
- Avg implementation time: [X] days
|
|
- Reusability: High
|
|
- Action: Extract as auth module
|
|
|
|
Pattern: Queue-based Background Processing
|
|
- Used in: [X] stories ([STORY-IDs])
|
|
- Success rate: [X]%
|
|
- Technologies: Laravel Queue, Redis
|
|
- Action: Create template
|
|
|
|
Recurring Architectures:
|
|
- Service Layer Pattern: [X] stories
|
|
- Repository Pattern: [X] stories
|
|
- Event-Driven: [X] stories
|
|
|
|
Technology Combinations:
|
|
- Livewire + Alpine.js: [X] stories
|
|
- Pest + Browser Tests: [X] stories
|
|
```
|
|
|
|
#### Phase 3: Problem Pattern Analysis
|
|
1. **EXTRACT** problems from progress logs
|
|
2. **CATEGORIZE** problems by type:
|
|
- Technical issues
|
|
- Integration challenges
|
|
- Performance problems
|
|
- Testing difficulties
|
|
- Deployment issues
|
|
|
|
3. **COUNT** frequency of each problem type
|
|
4. **LINK** problems to solutions
|
|
5. **IDENTIFY** root causes
|
|
|
|
6. **DISPLAY** problem patterns:
|
|
```
|
|
⚠️ RECURRING CHALLENGES
|
|
══════════════════════════════════
|
|
|
|
Common Problems:
|
|
|
|
Problem: N+1 Query Performance Issues
|
|
- Occurred: [X] times
|
|
- Stories: [STORY-IDs]
|
|
- Root cause: Missing eager loading
|
|
- Solution pattern: Add `with()` to queries
|
|
- Prevention: Code review checklist item
|
|
|
|
Problem: CORS Issues in API Integration
|
|
- Occurred: [X] times
|
|
- Stories: [STORY-IDs]
|
|
- Root cause: Middleware configuration
|
|
- Solution pattern: Configure cors.php
|
|
- Prevention: API setup template
|
|
|
|
Frequent Blockers:
|
|
- Third-party API rate limits: [X] occurrences
|
|
Mitigation: Implement caching layer
|
|
- Test environment setup: [X] occurrences
|
|
Mitigation: Docker compose template
|
|
```
|
|
|
|
#### Phase 4: Success Pattern Analysis
|
|
1. **IDENTIFY** high-performing stories:
|
|
- Fast completion times
|
|
- Zero bugs in QA
|
|
- First-time pass in review
|
|
|
|
2. **EXTRACT** success factors:
|
|
- Common approaches
|
|
- Best practices applied
|
|
- Tools and techniques used
|
|
|
|
3. **CALCULATE** success rates by pattern
|
|
4. **DETERMINE** velocity impact
|
|
|
|
5. **DISPLAY** success patterns:
|
|
```
|
|
✅ SUCCESS PATTERNS
|
|
══════════════════════════════════
|
|
|
|
High-Velocity Patterns:
|
|
|
|
Approach: TDD with Feature Tests First
|
|
- Used in: [X] stories
|
|
- Success rate: [X]%
|
|
- Avg completion: [X] days faster
|
|
- Key factors:
|
|
• Clear test cases upfront
|
|
• Fewer bugs in QA
|
|
• Confident refactoring
|
|
- Recommendation: Adopt as standard
|
|
|
|
Approach: Component-First UI Development
|
|
- Used in: [X] stories
|
|
- Success rate: [X]%
|
|
- Benefits:
|
|
• Reusable components
|
|
• Consistent design
|
|
• Faster iterations
|
|
- Best for: UI-heavy features
|
|
|
|
High-Quality Patterns:
|
|
- Livewire component testing: [X]% fewer bugs
|
|
- Browser E2E tests: [X]% fewer production issues
|
|
- Code review with checklist: [X]% first-time pass
|
|
```
|
|
|
|
#### Phase 5: Code Pattern Analysis
|
|
1. **SCAN** for reusable code structures:
|
|
- Component types
|
|
- Utility functions
|
|
- Service classes
|
|
- Middleware patterns
|
|
- Test helpers
|
|
|
|
2. **COUNT** instances of each pattern
|
|
3. **EVALUATE** reusability potential
|
|
4. **SUGGEST** extraction opportunities
|
|
|
|
5. **DISPLAY** code patterns:
|
|
```
|
|
💻 CODE PATTERNS
|
|
══════════════════════════════════
|
|
|
|
Reusable Components Identified:
|
|
|
|
Pattern: Form Validation Request Classes
|
|
- Instances: [X] similar implementations
|
|
- Stories: [STORY-IDs]
|
|
- Commonality: [X]% code overlap
|
|
- Candidate for: Base FormRequest class
|
|
- Estimated savings: [X] hours per story
|
|
|
|
Pattern: Livewire CRUD Components
|
|
- Instances: [X] similar implementations
|
|
- Stories: [STORY-IDs]
|
|
- Commonality: [X]% code overlap
|
|
- Candidate for: CRUD trait or base class
|
|
- Estimated savings: [X] hours per story
|
|
|
|
Pattern: API Response Formatters
|
|
- Instances: [X] similar implementations
|
|
- Candidate for: Shared utility package
|
|
- Extraction priority: High
|
|
|
|
Common Integrations:
|
|
- External API clients: [X] instances
|
|
Standard approach: Guzzle + DTO pattern
|
|
Template available: No
|
|
Action: Create API client template
|
|
```
|
|
|
|
#### Phase 6: Process Pattern Analysis
|
|
1. **ANALYZE** workflow patterns:
|
|
- Story progression times
|
|
- Review process effectiveness
|
|
- Testing strategies
|
|
- Deployment approaches
|
|
|
|
2. **IDENTIFY** effective practices:
|
|
- Time-of-day patterns
|
|
- Day-of-week patterns
|
|
- Story size sweet spots
|
|
- Review timing
|
|
|
|
3. **CALCULATE** process effectiveness metrics
|
|
|
|
4. **DISPLAY** process patterns:
|
|
```
|
|
📋 PROCESS PATTERNS
|
|
══════════════════════════════════
|
|
|
|
Effective Workflows:
|
|
|
|
Workflow: Same-day Review
|
|
- Stories: [X] with review within 24h
|
|
- Success rate: [X]%
|
|
- Avg cycle time: [X] days faster
|
|
- Recommendation: Target same-day reviews
|
|
|
|
Practice: Incremental Commits
|
|
- Stories: [X] with frequent commits
|
|
- Impact: [X]% easier code review
|
|
- Recommendation: Commit every feature increment
|
|
|
|
Timing Patterns:
|
|
- Stories started Monday: [X]% completion rate
|
|
- Stories started Friday: [X]% completion rate
|
|
- Optimal story size: [X] days
|
|
|
|
Risk Factors:
|
|
- Stories > 5 days: [X]% higher bug rate
|
|
- Stories with > 3 dependencies: [X]% longer cycle
|
|
```
|
|
|
|
#### Phase 7: Pattern Recommendations
|
|
1. **ANALYZE** all discovered patterns
|
|
2. **PRIORITIZE** by impact and effort:
|
|
- High impact, low effort: Quick wins
|
|
- High impact, high effort: Strategic initiatives
|
|
- Low impact, low effort: Nice to haves
|
|
|
|
3. **GENERATE** specific, actionable recommendations:
|
|
- Template creation
|
|
- Library extraction
|
|
- Process standardization
|
|
- Documentation needs
|
|
|
|
4. **DISPLAY** recommendations:
|
|
```
|
|
💡 PATTERN-BASED RECOMMENDATIONS
|
|
══════════════════════════════════
|
|
|
|
CREATE TEMPLATES FOR:
|
|
Priority: High
|
|
1. Authentication flow template
|
|
- Used in: [X] stories
|
|
- Estimated savings: [X] hours per story
|
|
- Template location: /templates/auth-flow.md
|
|
|
|
2. API integration template
|
|
- Used in: [X] stories
|
|
- Estimated savings: [X] hours per story
|
|
- Template location: /templates/api-integration.md
|
|
|
|
EXTRACT LIBRARIES FOR:
|
|
Priority: High
|
|
1. Form validation utilities
|
|
- Instances: [X] similar implementations
|
|
- Estimated savings: [X] hours per story
|
|
- Package name: app/Utils/FormValidation
|
|
|
|
2. API response formatters
|
|
- Instances: [X] similar implementations
|
|
- Estimated savings: [X] hours per story
|
|
- Package name: app/Http/Responses
|
|
|
|
STANDARDIZE PROCESSES:
|
|
Priority: Medium
|
|
1. Code review checklist
|
|
- Include: Performance checks, test coverage
|
|
- Expected impact: [X]% fewer QA bugs
|
|
|
|
2. Story sizing guidelines
|
|
- Optimal size: [X] days
|
|
- Expected impact: [X]% faster velocity
|
|
|
|
DOCUMENT PATTERNS:
|
|
Priority: Medium
|
|
1. JWT authentication pattern
|
|
- Location: /patterns/auth-jwt.md
|
|
- Include: Setup, usage, edge cases
|
|
```
|
|
|
|
#### Phase 8: Pattern Library Generation
|
|
1. **COMPILE** patterns into structured library
|
|
2. **CATEGORIZE** by domain:
|
|
- Authentication
|
|
- Data Processing
|
|
- API Integration
|
|
- UI Components
|
|
- Testing
|
|
|
|
3. **TRACK** usage and availability:
|
|
- Times used
|
|
- Template exists (yes/no)
|
|
- Documentation exists (yes/no)
|
|
- Action needed
|
|
|
|
4. **DISPLAY** pattern library:
|
|
```
|
|
📚 PATTERN LIBRARY
|
|
══════════════════════════════════
|
|
|
|
Category: Authentication
|
|
──────────────────────────────────
|
|
Pattern: JWT with Refresh Tokens
|
|
- Used in: 5 stories
|
|
- Success rate: 100%
|
|
- Template available: Yes (/templates/auth-jwt.md)
|
|
- Documentation: Yes (/patterns/auth-jwt.md)
|
|
|
|
Pattern: Social OAuth Integration
|
|
- Used in: 3 stories
|
|
- Success rate: 100%
|
|
- Template available: No
|
|
- Action: Create template
|
|
|
|
Category: Data Processing
|
|
──────────────────────────────────
|
|
Pattern: Queue-based Background Jobs
|
|
- Used in: 7 stories
|
|
- Success rate: 95%
|
|
- Template available: Yes (/templates/queue-job.md)
|
|
- Documentation: Yes (/patterns/queue-jobs.md)
|
|
|
|
Pattern: Batch Processing with Progress
|
|
- Used in: 3 stories
|
|
- Template available: No
|
|
- Action: Create template
|
|
|
|
Category: UI Components
|
|
──────────────────────────────────
|
|
Pattern: Livewire CRUD Components
|
|
- Used in: 12 stories
|
|
- Template available: No
|
|
- Action: Create base component trait
|
|
|
|
[Additional categories...]
|
|
```
|
|
|
|
#### Phase 9: Anti-Pattern Detection
|
|
1. **IDENTIFY** problematic patterns:
|
|
- Code smells that appear multiple times
|
|
- Approaches with low success rates
|
|
- Solutions that caused later problems
|
|
|
|
2. **ANALYZE** negative impact:
|
|
- Increased bug rates
|
|
- Longer cycle times
|
|
- Technical debt creation
|
|
|
|
3. **SUGGEST** better alternatives
|
|
|
|
4. **DISPLAY** anti-patterns:
|
|
```
|
|
❌ ANTI-PATTERNS TO AVOID
|
|
══════════════════════════════════
|
|
|
|
Anti-pattern: Direct DB Queries in Controllers
|
|
- Found in: [X] stories
|
|
- Problems caused:
|
|
• Difficult to test
|
|
• No reusability
|
|
• N+1 query issues
|
|
- Better approach: Use Repository or Query Builder
|
|
- Stories affected: [STORY-IDs]
|
|
|
|
Anti-pattern: Missing Validation in Livewire
|
|
- Found in: [X] stories
|
|
- Problems caused:
|
|
• Security vulnerabilities
|
|
• Data integrity issues
|
|
• Poor UX
|
|
- Better approach: Use #[Validate] attributes
|
|
- Stories affected: [STORY-IDs]
|
|
|
|
Anti-pattern: Monolithic Livewire Components
|
|
- Found in: [X] stories
|
|
- Problems caused:
|
|
• Hard to maintain
|
|
• Difficult to test
|
|
• Poor reusability
|
|
- Better approach: Break into smaller components
|
|
```
|
|
|
|
#### Phase 10: Pattern Export
|
|
1. **OFFER** to export patterns to structured files
|
|
2. **CREATE** pattern directory structure:
|
|
```
|
|
/patterns/
|
|
├── technical-patterns.md
|
|
├── success-patterns.md
|
|
├── anti-patterns.md
|
|
└── templates/
|
|
├── auth-flow.md
|
|
├── api-integration.md
|
|
└── queue-job.md
|
|
```
|
|
|
|
3. **GENERATE** markdown files with:
|
|
- Pattern descriptions
|
|
- Usage examples
|
|
- Code snippets
|
|
- Best practices
|
|
- Related stories
|
|
|
|
4. **DISPLAY** export summary:
|
|
```
|
|
💾 EXPORT PATTERNS
|
|
══════════════════════════════════
|
|
|
|
Files created:
|
|
✓ /patterns/technical-patterns.md (15 patterns)
|
|
✓ /patterns/success-patterns.md (8 patterns)
|
|
✓ /patterns/anti-patterns.md (5 patterns)
|
|
✓ /patterns/process-patterns.md (6 patterns)
|
|
|
|
Templates needed:
|
|
→ /templates/auth-jwt.md (create)
|
|
→ /templates/api-integration.md (create)
|
|
|
|
Next steps:
|
|
1. Review exported patterns
|
|
2. Create missing templates
|
|
3. Update coding standards
|
|
4. Share with team
|
|
```
|
|
|
|
### OUTPUTS
|
|
- Console display of all pattern analysis sections
|
|
- Optional: Pattern markdown files in `/patterns/` directory
|
|
- Optional: Template files in `/templates/` directory
|
|
|
|
### RULES
|
|
- MUST analyze only completed stories (read from `/docs/stories/completed/`)
|
|
- MUST identify patterns with 2+ occurrences (single instance not a pattern)
|
|
- MUST calculate accurate frequency and success metrics
|
|
- SHOULD provide specific story IDs as evidence
|
|
- SHOULD prioritize recommendations by impact
|
|
- SHOULD generate actionable insights
|
|
- NEVER modify story files (read-only operation)
|
|
- ALWAYS show pattern sources (which stories)
|
|
- ALWAYS suggest concrete next steps
|
|
- MUST handle missing data gracefully
|
|
|
|
## Pattern Categories
|
|
|
|
### Technical Patterns
|
|
- Implementation approaches (authentication, API, data processing)
|
|
- Architecture patterns (MVC, Repository, Event-Driven)
|
|
- Technology combinations (framework + library pairs)
|
|
- Integration patterns (external services, databases)
|
|
|
|
### Problem Patterns
|
|
- Recurring technical issues
|
|
- Common blockers
|
|
- Integration challenges
|
|
- Performance problems
|
|
- Root cause analysis
|
|
|
|
### Success Patterns
|
|
- High-velocity approaches
|
|
- High-quality techniques
|
|
- Effective workflows
|
|
- Best practices
|
|
|
|
### Code Patterns
|
|
- Reusable components
|
|
- Utility functions
|
|
- Service classes
|
|
- Test helpers
|
|
- Common structures
|
|
|
|
### Process Patterns
|
|
- Workflow effectiveness
|
|
- Timing patterns
|
|
- Story sizing
|
|
- Review practices
|
|
- Testing strategies
|
|
|
|
## Examples
|
|
|
|
### Example 1: All Patterns
|
|
```bash
|
|
INPUT:
|
|
/sdd:story-patterns
|
|
|
|
OUTPUT:
|
|
→ Scanning completed stories...
|
|
→ Found 42 completed stories
|
|
→ Analyzing patterns across all categories...
|
|
|
|
🔧 TECHNICAL PATTERNS FOUND
|
|
══════════════════════════════════
|
|
|
|
Pattern: JWT Authentication with Refresh Tokens
|
|
- Used in: 5 stories (STORY-2025-001, 012, 023, 034, 041)
|
|
- Success rate: 100%
|
|
- Avg implementation time: 2.4 days
|
|
- Reusability: High
|
|
- Action: Template available at /templates/auth-jwt.md
|
|
|
|
[Additional sections...]
|
|
|
|
💡 PATTERN-BASED RECOMMENDATIONS
|
|
══════════════════════════════════
|
|
|
|
CREATE TEMPLATES FOR:
|
|
1. API integration with retry logic (used in 8 stories)
|
|
2. Livewire form with validation (used in 15 stories)
|
|
|
|
[Additional recommendations...]
|
|
|
|
💾 Export patterns to /patterns/ directory? (y/n)
|
|
```
|
|
|
|
### Example 2: Technical Patterns Only
|
|
```bash
|
|
INPUT:
|
|
/sdd:story-patterns technical
|
|
|
|
OUTPUT:
|
|
→ Scanning completed stories...
|
|
→ Analyzing technical patterns only...
|
|
|
|
🔧 TECHNICAL PATTERNS FOUND
|
|
══════════════════════════════════
|
|
|
|
Common Implementations:
|
|
|
|
Pattern: Livewire Component with Alpine.js Enhancement
|
|
- Used in: 18 stories
|
|
- Technologies: Livewire 3, Alpine.js 3
|
|
- Success rate: 95%
|
|
- Common structure:
|
|
• Server-side state management
|
|
• Client-side UX enhancements
|
|
• Device-responsive behavior
|
|
|
|
[Additional technical patterns...]
|
|
```
|
|
|
|
### Example 3: No Patterns Found
|
|
```bash
|
|
INPUT:
|
|
/sdd:story-patterns
|
|
|
|
OUTPUT:
|
|
→ Scanning completed stories...
|
|
→ Found 3 completed stories
|
|
→ Analyzing patterns...
|
|
|
|
⚠️ INSUFFICIENT DATA
|
|
══════════════════════════════════
|
|
|
|
Not enough completed stories to identify patterns.
|
|
Patterns require at least 2 occurrences across multiple stories.
|
|
|
|
Current completed stories: 3
|
|
Minimum recommended: 10
|
|
|
|
Suggestions:
|
|
- Complete more stories to build pattern data
|
|
- Run /sdd:story-metrics to see development progress
|
|
- Check if stories are in /docs/stories/completed/
|
|
```
|
|
|
|
## Edge Cases
|
|
|
|
### Few Completed Stories
|
|
- DETECT insufficient story count (< 5)
|
|
- DISPLAY warning about pattern reliability
|
|
- SHOW limited patterns found
|
|
- SUGGEST completing more stories
|
|
|
|
### No Common Patterns
|
|
- DETECT when stories are highly unique
|
|
- DISPLAY "no recurring patterns" message
|
|
- SHOW individual story characteristics
|
|
- SUGGEST areas for potential standardization
|
|
|
|
### Inconsistent Story Format
|
|
- PARSE flexibly with fallbacks
|
|
- EXTRACT patterns from available data
|
|
- LOG warnings about incomplete data
|
|
- CONTINUE with best-effort analysis
|
|
|
|
### Missing Technical Notes
|
|
- SKIP pattern extraction from incomplete stories
|
|
- LOG which stories lack necessary sections
|
|
- CALCULATE patterns from complete data only
|
|
- SUGGEST standardizing story format
|
|
|
|
## Error Handling
|
|
- **No completed stories**: Inform user, suggest completing stories first
|
|
- **Permission errors**: Report specific file access issues
|
|
- **Malformed story files**: Skip problematic files, log warnings
|
|
- **Invalid category parameter**: Show valid options, use default
|
|
- **Export directory exists**: Ask to overwrite or merge
|
|
|
|
## Performance Considerations
|
|
- Efficient file scanning (single pass per directory)
|
|
- Lazy parsing (only parse when needed)
|
|
- Pattern matching with hash maps for speed
|
|
- Streaming output for large datasets
|
|
- Typical completion time: < 3 seconds for 50 stories
|
|
|
|
## Related Commands
|
|
- `/sdd:story-metrics` - Calculate velocity and quality metrics
|
|
- `/sdd:story-tech-debt` - Analyze technical debt
|
|
- `/sdd:project-status` - View current story statuses
|
|
- `/sdd:story-list` - List and filter stories
|
|
|
|
## Constraints
|
|
- ✅ MUST be read-only (no story modifications)
|
|
- ✅ MUST identify patterns with 2+ occurrences
|
|
- ✅ MUST provide evidence (story IDs)
|
|
- ⚠️ SHOULD prioritize by impact and frequency
|
|
- 📊 SHOULD include success rates
|
|
- 💡 SHOULD generate actionable recommendations
|
|
- 🔍 MUST show pattern sources
|
|
- ⏱️ MUST complete analysis in reasonable time (< 5s)
|
|
- 📁 SHOULD offer to export findings
|