/deep

Deep Refactor

**Comprehensive read-only analysis for large features and architectural changes.**

Safe to run anytime. Performs deep analysis against codebase patterns and writes detailed refactor plan without modifying files.

What This Does

Thorough, comprehensive code quality analysis that: 1. Classifies changes with detailed metrics 2. Deep analysis of backend and frontend architecture 3. Validates against ALL codebase patterns 4. Identifies architectural issues and violations 5. Generates comprehensive refactor plan 6. Writes detailed plan to `./tmp/` for review

When to Use

• **Large features** (10-20 files, 500-1000 lines)
• **Huge features** (20+ files, >1000 lines)
• **Architectural changes** requiring comprehensive validation
• **Pre-PR comprehensive check** for complex work

For small/medium changes, use `/simple-refactor` instead.

Process

Phase 0: Classification & Pattern Selection

**Analyze change metrics:**

git diff main --name-status
git diff main --numstat
git diff main --stat

**Classify:**

• **Size**: Large (500-1000 lines) | Huge (>1000 lines)
• **Type**: New Feature | Major Refactor | Enhancement
• **Complexity**: Complex | Very Complex
• **Layers**: Backend | Frontend | Both
• **Modules**: List affected modules

**Pattern Selection Matrix:**

| Size | Type | Universal | Architecture | Organization | Documentation | |------|------|-----------|--------------|--------------|---------------| | Large | Feature | ✓ | ✓ | ✓ | Required | | Huge | Feature | ✓ | ✓ | ✓ | Required |

**Show classification to user:**

📊 Change Classification:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Size:       Large (15 files, 742 lines changed)
Type:       New Feature (12 added, 3 modified)
Complexity: Complex (multiple modules)
Layers:     Backend (7 files), Frontend (8 files)
Modules:    feed, artifacts, workspace

📋 Patterns to Check:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✓ Universal (imports, errors, basic patterns)
✓ Architecture (controller-service, hooks, TanStack Query)
✓ Organization (orchestration hooks, underscore-prefix locality)
✓ Documentation (all new files must have documentation)

Proceeding with comprehensive analysis...

Phase 1: Backend Analysis

**Reference patterns from:**

• `apps/api/CLAUDE.md` - Complete backend architecture
• `CLAUDE.md` - Import conventions, shared library usage

**Exemplar files to study:**

• Controller: `apps/api/src/modules/feed/controllers/feed.controller.ts`
• Service: `apps/api/src/modules/feed/services/feed.service.ts`
• Validator: `apps/api/src/modules/feed/validators/feed-tag.validator.ts`
• Complex service: `apps/api/src/modules/audio/services/recording/` (folder pattern)

**Check patterns:**

**Controllers (apps/api/src/modules/*/controllers/):**

• ✓ Uses `authenticatedHandler` wrapper for auth routes
• ✓ Accesses `req.user` (provided by authenticatedHandler)
• ✓ Extracts params/query clearly at top
• ✓ Delegates to service methods (no business logic)
• ✓ Returns `{ success: true, data: ... }` format
• ✓ No database queries (in services)
• ✓ No try/catch blocks (authenticatedHandler handles)
• ✓ File-level documentation

**Services (apps/api/src/modules/*/services/):**

• ✓ Extends `BaseService` when using database
• ✓ Uses `this.db` for database access
• ✓ Contains ALL business logic
• ✓ Throws `ApiError` (not generic Error)
• ✓ Single responsibility (one domain concept)
• ✓ Complex services in subfolders with index.ts
• ✓ File-level documentation
• ✓ No controller logic leaking in

**Validators (apps/api/src/modules/*/validators/):**

• ✓ Uses Zod schemas
• ✓ Exports both schema and inferred types
• ✓ Validation NOT in controllers/services

**Import Patterns (Backend):**

• ✓ Uses `@/` for local API imports
• ✓ Uses `@doozy/shared` for shared types
• ✓ ZERO relative imports (`../`, `../../`)
• ✓ Imports organized: external, @doozy/shared, @/

**Database & Error Handling:**

• ✓ Drizzle ORM queries in services only
• ✓ ApiError thrown with proper status codes
• ✓ No raw SQL queries
• ✓ Proper transaction handling where needed

Phase 2: Frontend Analysis

**Reference patterns from:**

• `apps/webapp/CLAUDE.md` - Complete frontend architecture
• `apps/webapp/src/hooks/CLAUDE.md` - Hook patterns, TanStack Query
• `apps/webapp/src/components/CLAUDE.md` - Component patterns
• `CLAUDE.md` - Import conventions

**Exemplar files to study:**

• Page: `apps/webapp/src/app/(protected)/workspaces/[workspaceId]/feed/page.tsx`
• Orchestration Hook: `apps/webapp/src/app/(protected)/workspaces/[workspaceId]/archive/useArchivePage.ts`
• Shared Hook: `apps/webapp/src/hooks/feed/useFeed.ts`
• Component: Study underscore-prefix `_components/` vs `src/components/`

**Check patterns:**

**Pages (apps/webapp/src/app/*/page.tsx):**

• ✓ Has `'use client'` directive (most pages need it)
• ✓ Has file-level documentation comment
• ✓ Thin composition layer (mostly JSX)
• ✓ ALL logic in orchestration hooks (e.g., `usePage`)
• ✓ Calls `getMobileBottomSpacing(true)` for mobile pages
• ✓ No direct API calls (uses hooks)
• ✓ No state management (uses hooks)
• ✓ No business logic

**Orchestration Hooks (*/_hooks/usePage.ts):**

• ✓ Has file-level JSDoc explaining purpose
• ✓ Combines multiple hooks
• ✓ Contains business logic & event handlers
• ✓ Returns object with data/functions (NEVER JSX)
• ✓ Uses TanStack Query for server state
• ✓ Proper error handling with toast
• ✓ Query mutations invalidate related queries

**Underscore-Prefix Locality Convention:**

• ✓ Code in `_components/` only used by this page/feature
• ✓ Code in `_hooks/` only used by this page/feature
• ✓ Code in `_types/` only used by this page/feature
• ✓ Code in `_providers/` only used by this page/feature
• ✓ Code in `_utils/` only used by this page/feature
• ✓ Shared code (2+ features) in `src/`
• ✓ No underscore folders in `src/`

**Hooks (Shared or Local):**

• ✓ Name starts with `use` prefix
• ✓ NEVER returns JSX (returns data/functions only)

-