zhongwei/gh-ninthspace-claude-code-marketplace-sdd
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
d97a70be331ab765e3a939a4d772797f37f783bc
gh-ninthspace-claude-code-m…/commands/story-patterns.md
Zhongwei Li d97a70be33 Initial commit
2025-11-30 08:44:27 +08:00

19 KiB
Raw Blame History

/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

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

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

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
Reference in New Issue View Git Blame Copy Permalink