gh-cskiro-claudex/skills/analysis/bulletproof-react-auditor/reference/severity_matrix.md

Severity Matrix

Priority levels and response times for Bulletproof React audit findings.

Severity Levels

Critical (P0)

Fix immediately (within 24 hours)

Criteria

• Security vulnerabilities (tokens in localStorage, XSS risks)
• Breaking architectural violations that prevent scalability
• No testing framework in production app
• TypeScript strict mode disabled with widespread any usage

Examples

• Authentication tokens stored in localStorage
• No error boundaries in production app
• Zero test coverage on critical paths
• Multiple cross-feature dependencies creating circular imports

Impact

• Security breaches possible
• Application instability
• Cannot safely refactor or add features
• Technical debt compounds rapidly

---

High (P1)

Fix this sprint (within 2 weeks)

Criteria

• Major architectural misalignment with Bulletproof React
• No data fetching library (manual API state management)
• Test coverage < 80%
• Large components (> 400 LOC) with multiple responsibilities
• No features/ directory with >50 components

Examples

• Flat structure instead of feature-based
• Scattered fetch calls throughout components
• No React Query/SWR for server state
• Components with 15+ props
• No error tracking service (Sentry)

Impact

• Difficult to maintain and extend
• Poor developer experience
• Slow feature development
• Bugs hard to track and fix
• Testing becomes increasingly difficult

---

Medium (P2)

Fix next quarter (within 3 months)

Criteria

• Component design anti-patterns
• State management could be improved
• Missing recommended directories
• Some cross-feature imports
• No code splitting
• Inconsistent styling approaches

Examples

• Components 200-400 LOC
• Context with 5+ state values
• Too many shared components (should be feature-specific)
• Nested render functions instead of components
• Multiple styling systems in use
• Large images not optimized

Impact

• Code is maintainable but could be better
• Some technical debt accumulating
• Refactoring is more difficult than it should be
• Performance could be better
• Developer onboarding takes longer

---

Low (P3)

Backlog (schedule when convenient)

Criteria

• Minor deviations from Bulletproof React patterns
• Stylistic improvements
• Missing nice-to-have features
• Small optimizations

Examples

• Files not using kebab-case naming
• No Prettier configured
• No git hooks (Husky)
• Missing some recommended directories
• Test naming doesn't follow "should X when Y"
• Some components could be better colocated

Impact

• Minimal impact on development
• Minor inconsistencies
• Small developer experience improvements possible
• Low-priority technical debt

---

Effort Estimation

Low Effort (< 1 day)

• Installing dependencies
• Creating configuration files
• Renaming files
• Adding error boundaries
• Setting up Prettier/ESLint
• Configuring git hooks

Medium Effort (1-5 days)

• Creating features/ structure
• Organizing existing code into features
• Refactoring large components
• Adding React Query/SWR
• Setting up comprehensive error handling
• Improving test coverage to 80%

High Effort (1-3 weeks)

• Complete architecture restructuring
• Migrating from flat to feature-based structure
• Comprehensive security improvements
• Building out full test suite
• Large-scale refactoring
• Multiple concurrent improvements

---

Priority Decision Matrix

Severity	Effort Low	Effort Medium	Effort High
Critical	P0 - Do Now	P0 - Do Now	P0 - Plan & Start
High	P1 - This Sprint	P1 - This Sprint	P1 - This Quarter
Medium	P2 - Next Sprint	P2 - Next Quarter	P2 - This Year
Low	P3 - Backlog	P3 - Backlog	P3 - Nice to Have

---

Response Time Guidelines

Critical (P0)

• Notification: Immediate (Slack/email alert)
• Acknowledgment: Within 1 hour
• Plan: Within 4 hours
• Fix: Within 24 hours
• Verification: Immediately after fix
• Documentation: ADR created

High (P1)

• Notification: Within 1 day
• Acknowledgment: Within 1 day
• Plan: Within 2 days
• Fix: Within current sprint (2 weeks)
• Verification: Before sprint end
• Documentation: Updated in sprint retrospective

Medium (P2)

• Notification: Within 1 week
• Acknowledgment: Within 1 week
• Plan: Within sprint planning
• Fix: Within quarter (3 months)
• Verification: Quarterly review
• Documentation: Included in quarterly planning

Low (P3)

• Notification: Added to backlog
• Acknowledgment: During backlog refinement
• Plan: When capacity available
• Fix: Opportunistic
• Verification: As completed
• Documentation: Optional

---

Category-Specific Severity Guidelines

Structure Issues

• Critical: No features/, flat structure with 100+ components
• High: Missing features/, cross-feature dependencies
• Medium: Some organizational issues
• Low: Minor folder organization improvements

Component Issues

• Critical: Components > 1000 LOC, widespread violations
• High: Many components > 400 LOC, 15+ props
• Medium: Some large components, nested renders
• Low: Minor design improvements needed

State Management

• Critical: No proper state management in complex app
• High: No data fetching library, manual API state
• Medium: State could be better localized
• Low: Could use better state management tool

Testing Issues

• Critical: No testing framework, 0% coverage
• High: Coverage < 50%, wrong test distribution
• Medium: Coverage 50-79%, some brittle tests
• Low: Coverage > 80%, minor test improvements

Security Issues

• Critical: Tokens in localStorage, XSS vulnerabilities
• High: No error tracking, missing CSRF protection
• Medium: Minor security improvements needed
• Low: Security best practices could be better

---

Migration Planning

Phase 1: Critical (Week 1)

1. Fix all P0 security issues
2. Establish basic architecture (features/)
3. Set up testing framework
4. Configure error tracking

Phase 2: High Priority (Weeks 2-6)

1. Migrate to feature-based structure
2. Add React Query/SWR
3. Improve test coverage to 80%
4. Refactor large components
5. Add error boundaries

Phase 3: Medium Priority (Months 2-3)

1. Optimize component architecture
2. Implement code splitting
3. Improve state management
4. Add comprehensive testing
5. Performance optimizations

Phase 4: Low Priority (Ongoing)

1. Stylistic improvements
2. Developer experience enhancements
3. Documentation updates
4. Minor refactoring

---

Note: These guidelines should be adapted based on your team size, release cadence, and business priorities. Always balance technical debt reduction with feature development.