cursor-quality-suite 1.0.0

package/commands/code-quality/churn-map.md

@@ -0,0 +1,431 @@
+---
+description: Analyze git history to find high-churn files, hotspots, technical debt interest, and refactor candidates
+category: Context & Analysis
+aliases: [churn, hotspots, change-analysis, tech-debt]
+---
+
+# Churn Map - Analyze File Change Patterns
+
+Analyze file churn to identify hotspots, stable cores, **technical debt interest rate**, and refactor candidates.
+
+**Make refactoring discussions data-driven, not emotional.**
+
+## Usage
+
+```
+/churn-map {PATH}
+/churn-map {PATH} --last=6mo
+/churn-map {PATH} --compare=3mo,6mo,12mo    # Show trends
+/churn-map {PATH} --debt-rate               # Technical debt interest analysis
+/churn-map --repo                           # Full repo analysis
+```
+
+## Examples
+
+```
+/churn-map src/features/checkout
+/churn-map src/components --last=3mo
+/churn-map src/features/checkout/src/components --compare=3mo,6mo
+```
+
+## What This Produces
+
+```
+════════════════════════════════════════════════════════════════
+  CHURN MAP: src/features/checkout (Last 6 Months)
+════════════════════════════════════════════════════════════════
+
+📊 SUMMARY
+  Total files analyzed: 234
+  Total commits: 1,847
+  Unique authors: 23
+  Average commits/file: 7.9
+
+════════════════════════════════════════════════════════════════
+  🔴 HIGH CHURN (Top 10 Hotspots)
+════════════════════════════════════════════════════════════════
+
+| Rank | File | Commits | Authors | Churn Score |
+|------|------|---------|---------|-------------|
+| 1 | MainWithBooking.tsx | 145 | 12 | 🔥 Critical |
+| 2 | BookingDetails.tsx | 128 | 8 | 🔥 Critical |
+| 3 | PackagesV2.tsx | 89 | 6 | 🔥 Critical |
+| 4 | helpers.ts | 67 | 5 | ⚠️ High |
+| 5 | useCheckoutState.ts | 54 | 7 | ⚠️ High |
+| 6 | PaymentForm.tsx | 48 | 4 | ⚠️ High |
+| 7 | ProtectionPackageCard.tsx | 42 | 5 | ⚠️ High |
+| 8 | CoverageAndAddOns.tsx | 38 | 4 | ⚠️ High |
+| 9 | VehicleSelection.tsx | 35 | 3 | 🟡 Medium |
+| 10 | types/index.ts | 32 | 6 | 🟡 Medium |
+
+Recommendation: Files with 🔥 Critical churn are candidates for:
+  - /migration-plan (structured decomposition)
+  - /refactor-new --churn-aware (prioritized refactoring)
+
+════════════════════════════════════════════════════════════════
+  🟢 STABLE CORE (Bottom 10 - Don't Touch)
+════════════════════════════════════════════════════════════════
+
+| Rank | File | Commits | Last Changed | Status |
+|------|------|---------|--------------|--------|
+| 1 | constants.ts | 2 | 5 months ago | 🛡️ Stable |
+| 2 | Layout.tsx | 3 | 4 months ago | 🛡️ Stable |
+| 3 | theme.ts | 4 | 3 months ago | 🛡️ Stable |
+| 4 | ErrorBoundary.tsx | 3 | 6 months ago | 🛡️ Stable |
+| 5 | useMediaQuery.ts | 5 | 4 months ago | 🛡️ Stable |
+
+⚠️ Warning: Touching stable files increases risk.
+   These files rarely change because they work well.
+   Refactoring here requires strong justification.
+
+════════════════════════════════════════════════════════════════
+  📈 CHURN TRENDS
+════════════════════════════════════════════════════════════════
+
+MainWithBooking.tsx:
+  Last 3 months: 45 commits  ████████████████████
+  Previous 3mo:  62 commits  ██████████████████████████████
+  Trend: ↓ Decreasing (-27%) ✅
+
+BookingDetails.tsx:
+  Last 3 months: 58 commits  ██████████████████████████
+  Previous 3mo:  42 commits  ██████████████████
+  Trend: ↑ Increasing (+38%) ⚠️
+
+PackagesV2.tsx:
+  Last 3 months: 52 commits  ████████████████████████
+  Previous 3mo:  37 commits  █████████████████
+  Trend: ↑ Increasing (+41%) ⚠️
+
+════════════════════════════════════════════════════════════════
+  🎯 REFACTOR CANDIDATES
+════════════════════════════════════════════════════════════════
+
+Based on churn analysis, prioritize these refactors:
+
+1. 🔴 MainWithBooking.tsx (770 lines, 145 commits)
+   Problem: Too many responsibilities
+   Suggested: Split into route + providers + steps
+   ROI: High (reduces merge conflicts significantly)
+
+2. 🔴 BookingDetails.tsx (1,148 lines, 128 commits)
+   Problem: God component, increasing churn
+   Suggested: Extract sections into sub-components
+   ROI: Very High (biggest pain point)
+
+3. 🟠 PackagesV2.tsx (450 lines, 89 commits)
+   Problem: Mixed concerns, growing complexity
+   Suggested: Extract package-specific logic to hooks
+   ROI: Medium-High
+
+Run: /migration-plan to generate detailed refactor plans
+
+════════════════════════════════════════════════════════════════
+  💰 ROI ESTIMATION (Data-Driven Justification)
+════════════════════════════════════════════════════════════════
+
+## Refactoring Investment Analysis
+
+| File | Refactor Effort | Maintenance Saved | Payback | ROI |
+|------|-----------------|-------------------|---------|-----|
+| BookingDetails.tsx | 24h | 8h/month | 3 months | 📈 300% |
+| MainWithBooking.tsx | 16h | 5h/month | 3.2 months | 📈 275% |
+| PackagesV2.tsx | 8h | 2h/month | 4 months | 📈 200% |
+
+## Calculation Methodology
+
+### Maintenance Cost (Current State)
+Based on 6-month churn analysis:
+
+| File | Merge Conflicts | Debug Time | PR Revisions | Monthly Cost |
+|------|-----------------|------------|--------------|--------------|
+| BookingDetails.tsx | 12/mo | 4h/mo | 3/mo | ~8h |
+| MainWithBooking.tsx | 8/mo | 3h/mo | 2/mo | ~5h |
+| PackagesV2.tsx | 4/mo | 1h/mo | 1/mo | ~2h |
+
+### Refactoring Investment
+| File | Analysis | Implementation | Testing | Review | Total |
+|------|----------|----------------|---------|--------|-------|
+| BookingDetails.tsx | 4h | 12h | 4h | 4h | 24h |
+| MainWithBooking.tsx | 2h | 10h | 2h | 2h | 16h |
+| PackagesV2.tsx | 1h | 4h | 2h | 1h | 8h |
+
+### 12-Month Projection
+
+```
+
+BookingDetails.tsx:
+Refactor cost: 24 hours
+Maintenance saved: 8h × 12 = 96 hours
+Net savings: 72 hours ✅
+
+MainWithBooking.tsx:
+Refactor cost: 16 hours
+Maintenance saved: 5h × 12 = 60 hours
+Net savings: 44 hours ✅
+
+PackagesV2.tsx:
+Refactor cost: 8 hours
+Maintenance saved: 2h × 12 = 24 hours
+Net savings: 16 hours ✅
+
+TOTAL ANNUAL SAVINGS: 132 hours (~3.3 weeks developer time)
+
+```
+
+### Business Impact
+
+| Metric | Before Refactor | After (Projected) |
+|--------|-----------------|-------------------|
+| Avg PR merge time | 2.3 days | 1.1 days |
+| Merge conflicts/week | 8 | 2 |
+| Regression rate | 12% | 4% |
+| Onboarding time | 3 weeks | 1.5 weeks |
+
+### Executive Summary
+
+> **Investment:** 48 engineering hours (1 week)
+> **Return:** 132 hours saved annually
+> **Payback Period:** ~3 months
+> **ROI:** 275%
+
+Recommendation: ✅ Prioritize BookingDetails.tsx refactoring in next sprint
+
+════════════════════════════════════════════════════════════════
+  📉 TECHNICAL DEBT INTEREST RATE
+════════════════════════════════════════════════════════════════
+
+## What is Technical Debt Interest Rate?
+
+The "interest" you pay on technical debt is the ongoing cost of NOT refactoring:
+- Extra time on every PR touching that file
+- Merge conflicts
+- Debugging time
+- Onboarding friction
+- Regression fixes
+
+## Debt Interest Calculation
+
+### Per-File Interest Rate
+
+| File | Change Freq | Avg PR Time | Conflict Rate | Interest/Month |
+|------|-------------|-------------|---------------|----------------|
+| BookingDetails.tsx | 21/mo | +2.1 days | 38% | **8.4 dev-hours** |
+| MainWithBooking.tsx | 18/mo | +1.8 days | 32% | **6.2 dev-hours** |
+| PackagesV2.tsx | 14/mo | +0.9 days | 18% | **3.1 dev-hours** |
+| helpers.ts | 11/mo | +0.5 days | 12% | **1.8 dev-hours** |
+
+### Formula
+
+```
+
+Debt Interest = (Change Frequency × Extra PR Time) + (Conflict Rate × Conflict Resolution Time)
+
+Where:
+
+-   Change Frequency = commits/month
+-   Extra PR Time = time above baseline for files of similar size
+-   Conflict Rate = % of merges with conflicts
+-   Resolution Time = avg time to resolve conflicts
+
+```
+
+### Aggregate Debt Interest
+
+```
+
+════════════════════════════════════════════════════════════════
+TOP 10 DEBT INTEREST PAYERS
+════════════════════════════════════════════════════════════════
+
+│ Rank │ File │ Interest/Month │ Annual Cost │
+│------│-----------------------│----------------|-------------|
+│ 1 │ BookingDetails.tsx │ 8.4 hours │ 100.8 hours │
+│ 2 │ MainWithBooking.tsx │ 6.2 hours │ 74.4 hours │
+│ 3 │ PackagesV2.tsx │ 3.1 hours │ 37.2 hours │
+│ 4 │ helpers.ts │ 1.8 hours │ 21.6 hours │
+│ 5 │ useCheckoutState.ts │ 1.5 hours │ 18.0 hours │
+│------│-----------------------│----------------|-------------|
+│ │ TOTAL TOP 5 │ 21.0 hours/mo │ 252 hours │
+│ │ (Equivalent) │ (~3 dev-days) │ (~6 weeks) │
+════════════════════════════════════════════════════════════════
+
+Annual cost of NOT refactoring top 5 files: ~6 weeks of dev time
+
+```
+
+### Debt Payoff Analysis
+
+```
+
+┌─────────────────────────────────────────────────────────────┐
+│ REFACTOR vs CONTINUE PAYING INTEREST │
+├─────────────────────────────────────────────────────────────┤
+│ │
+│ BookingDetails.tsx │
+│ ├── Current debt interest: 8.4 hours/month │
+│ ├── Refactor investment: 24 hours (one-time) │
+│ ├── Post-refactor interest: ~1.2 hours/month │
+│ ├── Monthly savings: 7.2 hours │
+│ └── Payback period: 3.3 months │
+│ │
+│ RECOMMENDATION: ✅ Refactor NOW │
+│ Every month delayed = 7.2 hours wasted │
+│ │
+└─────────────────────────────────────────────────────────────┘
+
+```
+
+### Velocity Impact
+
+How debt affects team velocity:
+
+```
+
+│ Metric │ Current │ Post-Refactor │ Improvement │
+│---------------------------│---------|---------------|-------------|
+│ Avg PR merge time │ 2.3 days│ 1.1 days │ -52% │
+│ Merge conflicts/week │ 8 │ 2 │ -75% │
+│ Regression rate │ 12% │ 4% │ -67% │
+│ New dev onboarding │ 3 weeks │ 1.5 weeks │ -50% │
+│ Time to first PR │ 5 days │ 2 days │ -60% │
+
+```
+
+════════════════════════════════════════════════════════════════
+  👥 AUTHOR CONCENTRATION
+════════════════════════════════════════════════════════════════
+
+Files with single-author concentration (bus factor risk):
+
+| File | Primary Author | % of Commits |
+|------|----------------|--------------|
+| PaymentFlow.tsx | @dev-1 | 78% ⚠️ |
+| usePaymentState.ts | @dev-1 | 85% ⚠️ |
+| CheckoutTracking.ts | @dev-2 | 92% ⚠️ |
+
+Recommendation: Schedule knowledge sharing for these files.
+
+════════════════════════════════════════════════════════════════
+```
+
+## Churn Scoring
+
+| Score       | Commits/6mo | Authors | Action                       |
+| ----------- | ----------- | ------- | ---------------------------- |
+| 🔥 Critical | >100        | >5      | Immediate refactor candidate |
+| ⚠️ High     | 50-100      | 3-5     | Consider refactoring         |
+| 🟡 Medium   | 20-50       | 2-4     | Monitor                      |
+| 🟢 Low      | <20         | 1-2     | Stable, protect              |
+| 🛡️ Stable   | <5          | any     | Core, don't touch            |
+
+## Commands Used
+
+```bash
+# Get commit count per file
+git log --since="6 months ago" --name-only --pretty=format: | \
+  sort | uniq -c | sort -rn
+
+# Get authors per file
+git log --since="6 months ago" --format='%an' -- {FILE} | \
+  sort | uniq -c | sort -rn
+
+# Get commit frequency over time
+git log --since="6 months ago" --format='%ai' -- {FILE} | \
+  cut -d- -f1-2 | sort | uniq -c
+
+# Get merge conflict history
+git log --since="6 months ago" --all --oneline --grep="Merge conflict" -- {PATH}
+
+# Get files changed together (coupling)
+git log --since="6 months ago" --name-only --pretty=format: | \
+  awk 'NF' | sort | uniq -c | sort -rn
+```
+
+## Integration with Other Commands
+
+| Use Before                    | Why                                                |
+| ----------------------------- | -------------------------------------------------- |
+| `/migration-plan`             | Identify which files need structured decomposition |
+| `/refactor-new --churn-aware` | Focus effort on high-ROI files                     |
+| `/full-flow`                  | Understand if your changes touch hotspots          |
+| `/pr-review`                  | Context on file stability                          |
+| `/decision-record`            | Document why stable files should stay stable       |
+
+## Compare Mode
+
+See how churn changes over time:
+
+```
+/churn-map src/features/checkout --compare=3mo,6mo,12mo
+```
+
+Output:
+
+```
+════════════════════════════════════════════════════════════════
+  CHURN COMPARISON: src/features/checkout
+════════════════════════════════════════════════════════════════
+
+MainWithBooking.tsx:
+  Last 3mo:  45 commits  ████████████████
+  Last 6mo:  107 commits ████████████████████████████████████
+  Last 12mo: 189 commits ████████████████████████████████████████████████████
+
+  Trend: Decreasing ↓ (good! refactoring is working)
+
+BookingDetails.tsx:
+  Last 3mo:  58 commits  ██████████████████████
+  Last 6mo:  100 commits ██████████████████████████████████████
+  Last 12mo: 145 commits ████████████████████████████████████████████████
+
+  Trend: Stable → (needs attention)
+
+PackagesV2.tsx:
+  Last 3mo:  52 commits  ████████████████████
+  Last 6mo:  89 commits  ██████████████████████████████████
+  Last 12mo: 89 commits  ██████████████████████████████████
+
+  Trend: Increasing ↑ (recent growth, monitor closely)
+```
+
+## Coupling Analysis
+
+Find files that change together (hidden dependencies):
+
+```
+/churn-map src/features/checkout --coupling
+```
+
+Output:
+
+```
+════════════════════════════════════════════════════════════════
+  FILE COUPLING ANALYSIS
+════════════════════════════════════════════════════════════════
+
+Files frequently changed together:
+
+1. PackagesV2.tsx + helpers.ts
+   Co-changed: 34 times (67%)
+   → Consider: Merging or explicit interface
+
+2. MainWithBooking.tsx + useCheckoutState.ts
+   Co-changed: 28 times (54%)
+   → Consider: These are tightly coupled
+
+3. types/index.ts + 15 other files
+   Co-changed: 89 times
+   → Consider: Type changes have wide impact
+```
+
+## AI Execution
+
+When user runs `/churn-map {PATH}`:
+
+1. **Run git analysis** on the specified path
+2. **Calculate churn scores** for each file
+3. **Identify trends** (increasing/decreasing)
+4. **Flag refactor candidates** based on scores
+5. **Identify stable core** files to protect
+6. **Generate recommendations** with ROI estimates

package/commands/code-quality/code-standards.md

@@ -0,0 +1,219 @@
+---
+description: Reference guide for code quality standards, component limits, hook patterns
+category: Code Quality
+aliases: [standards, quality, limits]
+---
+
+# Code Standards Enforcement
+
+Guidelines based on historical codebase analysis.
+
+**Purpose:** Reference for analytical commands (not real-time enforcement)
+
+**Auto-enforced version:** `.cursor/rules/web-standards.mdc` (enforces while typing)
+
+**Used by:** `/full-flow`, `/pr-review`, `/pr-fix`, `/pr-checklist`, `/migration-plan`
+
+**Run automated check:**
+
+```bash
+.cursor/scripts/code-quality-check.sh {PATH}
+```
+
+> **Note:** Static constraints are auto-enforced by `.mdc` rules.
+> This command provides the reference documentation and analytical context.
+
+## Component Size Limits (MUST ENFORCE)
+
+When generating or reviewing code, check these limits:
+
+| Metric          | ✅ Target | ⚠️ Warning | 🔴 Refactor |
+| --------------- | --------- | ---------- | ----------- |
+| Lines of code   | < 150     | 150-300    | > 300       |
+| Imports         | < 20      | 20-35      | > 35        |
+| useState calls  | < 4       | 4-6        | > 6         |
+| useEffect calls | < 3       | 3-5        | > 5         |
+| Custom hooks    | < 8       | 8-15       | > 15        |
+
+### Enforcement Actions
+
+**When generating new code:**
+
+-   NEVER create components exceeding warning limits
+-   Split into sub-components proactively
+-   Extract hooks for complex logic
+
+**When reviewing existing code:**
+
+-   Flag violations in review comments
+-   Suggest decomposition strategy
+-   Reference this checklist
+
+## Feature Structure (MUST FOLLOW)
+
+```
+FeatureName/
+├── FeatureName.tsx              # Orchestrator (< 100 lines)
+├── FeatureName.styled.ts        # Styles only
+├── FeatureName.types.ts         # Types/interfaces
+├── FeatureName.test.tsx         # Tests
+├── FeatureName.mock.ts          # Shared mocks
+│
+├── hooks/                       # Feature-specific hooks
+│   ├── useFeatureState.ts
+│   ├── useFeatureData.ts
+│   └── useFeatureTracking.ts
+│
+├── components/                  # Sub-components (each < 150 lines)
+│   ├── FeatureHeader/
+│   ├── FeatureContent/
+│   └── FeatureActions/
+│
+└── utils/
+    └── helpers.ts
+```
+
+## Hook Design Rules
+
+### ✅ GOOD Patterns
+
+```typescript
+// Single responsibility
+export const useFeatureData = (id: string) => {
+    // Only data fetching logic
+};
+
+// Composition
+export const useFeature = () => {
+    const data = useFeatureData();
+    const state = useFeatureState();
+    return { ...data, ...state };
+};
+
+// AbortController for async
+useEffect(() => {
+    const controller = new AbortController();
+    fetchData({ signal: controller.signal });
+    return () => controller.abort();
+}, [dep]);
+```
+
+### ❌ BAD Patterns (NEVER Generate)
+
+```typescript
+// God hook with 30+ returns
+export const useEverything = () => {
+    const [a, setA] = useState();
+    const [b, setB] = useState();
+    // ... 15 more states
+    useEffect(() => {}, []);
+    useEffect(() => {}, []);
+    // ... 8 more effects
+    return { a, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p };
+};
+
+// Missing cleanup
+useEffect(() => {
+    fetchData().then(setData); // Race condition!
+}, []);
+
+// watch() instead of useWatch
+const value = methods.watch(); // Causes re-renders
+```
+
+## Styling Rules
+
+### ALWAYS Use Design Tokens
+
+```typescript
+// ✅ GOOD
+import { spacing } from '@your-org/design-system/src/utils/spacing';
+import { color } from '@your-org/design-system/src/utils/colors';
+
+padding: ${spacing('xs')};
+background: ${color('container1')};
+
+// ❌ BAD - Never hardcode
+padding: 16px;
+background: #ffffff;
+```
+
+### Responsive Patterns
+
+```typescript
+import { OXBiggerThan } from '@your-org/design-system/src/enums/OXBiggerThan';
+
+// ✅ GOOD
+@media ${OXBiggerThan.Small} {
+    padding: ${spacing('m')};
+}
+
+// ❌ BAD
+@media (min-width: 768px) {
+    padding: 24px;
+}
+```
+
+## State Management Rules
+
+### Colocation Principle
+
+```typescript
+// ✅ State where it's used
+const FeatureSection = () => {
+    const [isOpen, setIsOpen] = useState(false);
+    return <Collapsible open={isOpen} />;
+};
+
+// ✅ Context for shared state
+const FeatureProvider = ({ children }) => {
+    const [state, dispatch] = useReducer(reducer, initial);
+    return (
+        <FeatureContext.Provider value={{ state, dispatch }}>
+            {children}
+        </FeatureContext.Provider>
+    );
+};
+
+// ❌ Prop drilling > 3 levels
+<A data={x}><B data={x}><C data={x}><D data={x} /></C></B></A>
+```
+
+## Import Organization
+
+```typescript
+// 1. External libraries
+import { useState, useEffect } from 'react';
+
+// 2. YourCompany packages (alphabetical)
+import { useOXBreakpoint } from '@your-org/design-system';
+import { OXTypography } from '@your-org/design-system/src/ui/components/p100/Typography';
+
+// 3. Relative imports
+import * as S from './Component.styled';
+import type { IComponent } from './Component.types';
+import { useComponentData } from './hooks/useComponentData';
+```
+
+## Decomposition Triggers
+
+When you see these patterns, IMMEDIATELY suggest decomposition:
+
+1. **File > 300 lines** → Split by responsibility
+2. **> 6 useState** → Extract to useReducer or custom hook
+3. **> 5 useEffect** → Split into focused hooks
+4. **> 35 imports** → Component doing too much
+5. **Nested ternaries** → Extract to sub-components
+6. **Repeated JSX blocks** → Extract to component
+
+## Quick Check Before Generating
+
+Before generating any component:
+
+-   [ ] Will it exceed 150 lines?
+-   [ ] Does it need > 4 useState?
+-   [ ] Does it need > 3 useEffect?
+-   [ ] Are there > 20 imports?
+-   [ ] Is there a simpler decomposition?
+
+If ANY answer is "yes", restructure BEFORE generating.