/code-surgeon "GitHub issue URL or plain text requirement"

Input: {
  // Task to implement
  task: {
    task_id: string;
    title: string;
    description: string;
    files_affected: string[];
    success_criteria: string[];
    dependencies: string[];
    verification_approach: string;
  };

  // Design context from Implementation Planner
  design_choices: Array<{
    decision: string;
    recommended: string;
    rationale: string;
  }>;

  breaking_changes: Array<{
    type: string;
    description: string;
    migration_path: string;
  }>;

  // Context from Phases 1-3
  framework: string;
  language: string;
  patterns_found: Array<{name, description, examples}>;
  team_conventions: string[];
  files_selected: Array<{path, tier, content}>;
}

Output: {
  prompt_id: string;
  task_id: string;
  objective: string;  // 1-2 sentence goal
  context: string;    // Why this matters
  scope: {
    files_to_modify: string[];
    files_to_reference: string[];
    files_to_avoid: string[];
  };
  approach: string;   // Framework-specific how-to
  patterns: Array<{
    name: string;
    example_file: string;
    application: string;
  }>;
  constraints: string[];  // Team conventions
  breaking_changes: Array<{
    change: string;
    impact: string;
    migration: string;
  }>;
  success_criteria: string[];
  common_mistakes: string[];
  verification: Array<{
    step: string;
    expected_result: string;
  }>;
}

Example:
  "Create a dark mode toggle component that detects system preference
   and allows manual override, storing selection in localStorage."

Example:
  "Dark mode is critical for user experience in nighttime environments.
   This task provides the core toggle mechanism that Phase 2 will integrate
   with the theme system. Getting this right unblocks the UI styling work."

Example:
  Modify:
    - src/components/ThemeToggle.tsx (NEW)
    - src/hooks/useThemePreference.ts (NEW)
    - src/App.tsx (add theme provider)

  Reference:
    - src/hooks/useLocalStorage.ts (for persistence pattern)
    - src/context/ThemeContext.tsx (understand theme structure)

  Avoid:
    - Do NOT modify any existing components
    - Do NOT add new dependencies to package.json
    - Do NOT modify CSS files (handled in Phase 2)

React example:
  "This uses React hooks pattern:
   1. useThemePreference hook manages system/user preference state
   2. ThemeToggle component provides UI for user override
   3. useLocalStorage hook persists choice (see reference file)
   4. No external CSS - use CSS-in-JS for theme application"

Django example:
  "This adds a new model and API:
   1. Create UserPreference model with color_mode field
   2. Create PreferenceSerializer for validation
   3. Add update endpoint to UserViewSet
   4. Add tests for preference persistence"

Example:
  "Pattern 1: Custom Hooks for State
    See src/hooks/useLocalStorage.ts - similar pattern for localStorage.
    Apply: Create useThemePreference hook following this structure.

   Pattern 2: React Context for Global State
    See src/context/ThemeContext.tsx - how theme is provided globally.
    Apply: Integrate theme toggle with existing ThemeContext.

   Pattern 3: Component Composition
    See src/components/Settings/Toggle.tsx - how toggles are styled.
    Apply: Use similar Toggle component structure for theme toggle."

Example:
  "Code Style:
    - Use TypeScript (all React components must be .tsx)
    - Use functional components, never class components
    - Name components in PascalCase, hooks in camelCase

  Architectural:
    - Store all state in hooks or context, never in globals
    - Use React hooks, not Higher-Order Components
    - Prefer composition over inheritance

  Testing:
    - Write unit tests for every exported function
    - Use React Testing Library, not enzyme
    - Test behavior, not implementation details

  Documentation:
    - Add JSDoc comments for exported functions
    - Add inline comments for complex logic"

Example (if applicable):
  "Breaking Changes:
    1. useTheme hook signature changes
       - Old: useTheme() returns {isDark: bool}
       - New: useTheme() returns {isDark: bool, toggleTheme: () => void}
       - Impact: Any component using useTheme needs update
       - Migration: Add toggleTheme param to component props

    2. ThemeContext structure changes
       - Adds 'userPreference' field
       - Existing code still works (backward compatible)"

Example:
  "✓ Component renders without errors
  ✓ System preference detected correctly (test with prefers-color-scheme)
  ✓ Manual toggle works (click changes state)
  ✓ Selection persists across page refresh (localStorage)
  ✓ Tests pass: npm test ThemeToggle
  ✓ TypeScript compiles without errors
  ✓ Code style passes: npm run lint
  ✓ Component integrates with ThemeContext (tested in integration test)"

Example:
  "❌ Using window.matchMedia but not handling listener cleanup
    ✓ Solution: Return cleanup function from useEffect

  ❌ Using localStorage without checking if available
    ✓ Solution: Use try/catch or custom useLocalStorage hook

  ❌ Creating new function on every render
    ✓ Solution: Use useCallback for toggle handler

  ❌ Forgetting to add dependency array to useEffect
    ✓ Solution: Always include dependencies (use ESLint rule)

  ❌ Not testing system preference changes
    ✓ Solution: Test with matchMedia mock in tests"

This task uses React hooks and component patterns:
- Create [component_name] component with [specific hooks]
- Use custom hooks for [state/side effects]
- Follow [pattern name] from src/[path]
- Styling approach: [CSS-in-JS | CSS modules | Tailwind]

Key Patterns in Your Codebase:
- Custom hooks (see src/hooks)
- Component composition (see src/components)
- State management (see [context/redux pattern])

This task adds a Django model/view/serializer:
- Create model with [specific fields]
- Create serializer with [validation rules]
- Create viewset with [specific endpoints]
- Add URL routing in [specific urls file]

Key Patterns in Your Codebase:
- Model definition (see models.py)
- Serializer pattern (see serializers.py)
- ViewSet pattern (see views.py)

This task implements a Go interface/handler:
- Define [interface_name] interface
- Implement [handler_name] handler
- Add error handling for [specific cases]
- Integrate with router/middleware

Key Patterns in Your Codebase:
- Interface definitions (see handlers.go)
- Error handling (see pkg/errors)
- Testing pattern (see _test.go)

Context Limits:
  - Task scope: 2K-5K tokens
  - Code examples: 3K-8K tokens
  - Framework guidance: 1K-3K tokens
  - Success criteria: 500-1K tokens
  - Total: 7K-17K tokens per task

Large Task Handling:
  If task requires >25K tokens:
    1. Break into sub-tasks
    2. Defer context to references
    3. Use abstract descriptions
    4. Prioritize core files

Small task (1-2 files):
  - Context: 2K tokens
  - Examples: 2K tokens
  - Total: ~5K tokens

Medium task (3-5 files):
  - Context: 4K tokens
  - Examples: 4K tokens
  - Total: ~10K tokens

Large task (6+ files):
  - Split into sub-tasks
  - Keep each <15K tokens

OBJECTIVE:
Create a dark mode toggle component that detects system preference
and allows manual override, storing selection in localStorage.

CONTEXT:
Dark mode is critical for user experience in nighttime environments.
This component provides the core toggle mechanism that Phase 2 integrates
with the theme system. Getting this right unblocks the UI styling work.

SCOPE:
Modify:
  - src/components/ThemeToggle.tsx (CREATE NEW)
  - src/hooks/useThemePreference.ts (CREATE NEW)
  - src/App.tsx (add theme provider wrapper)

Reference:
  - src/hooks/useLocalStorage.ts (for persistence pattern)
  - src/context/ThemeContext.tsx (understand theme structure)
  - src/components/Settings/Toggle.tsx (UI component pattern)

Avoid:
  - Do NOT modify CSS files (Phase 2)
  - Do NOT add new npm dependencies
  - Do NOT modify any other components

APPROACH:
This uses React hooks pattern:
1. useThemePreference hook manages system/user preference state
2. ThemeToggle component provides UI for user override
3. useLocalStorage hook persists choice across sessions
4. Integrate with existing ThemeContext

Key decisions already made:
- Use hooks, not class components
- CSS-in-JS styling (handled in next phase)
- No external UI libraries
- localStorage for persistence

PATTERNS:
Pattern 1: Custom Hook for State & Effects
  See src/hooks/useLocalStorage.ts
  Apply: Create useThemePreference hook following this structure
  Why: Encapsulates theme preference logic, reusable

Pattern 2: React Context for Global State
  See src/context/ThemeContext.tsx
  Apply: Provider wraps App, toggle reads/writes context
  Why: Makes theme available to all components

Pattern 3: System Preference Detection
  See src/utils/mediaQuery.ts (uses matchMedia)
  Apply: Use prefers-color-scheme media query listener
  Why: Respects user's OS dark mode setting

CONSTRAINTS:
Code Style:
  - All React components: TypeScript (.tsx)
  - Functional components only (no classes)
  - Components: PascalCase, hooks: camelCase

Architecture:
  - Store all state in hooks/context
  - Use React hooks exclusively
  - Prefer composition over inheritance

Testing:
  - Write unit tests for every exported function
  - Use React Testing Library
  - Test behavior, not implementation

Documentation:
  - Add JSDoc for exported functions
  - Add comments for complex logic
  - Add type annotations

SUCCESS CRITERIA:
✓ Component renders without console errors
✓ System preference detected (prefers-color-scheme works)
✓ Manual toggle changes selection
✓ Selection persists after page refresh
✓ Tests pass: npm test ThemeToggle ThemePreference
✓ TypeScript compiles: npm run type-check
✓ Code style: npm run lint (no warnings)
✓ Integrates with ThemeContext (context updated)
✓ No console warnings/errors in browser DevTools

COMMON MISTAKES:
❌ Forgetting to cleanup matchMedia listener
  ✓ Return cleanup from useEffect: return () => mediaQuery.removeListener(...)

❌ Not checking localStorage availability (some browsers private mode)
  ✓ Wrap in try/catch or use custom hook that handles this

❌ Creating new function on every render (new toggleTheme each time)
  ✓ Wrap handler in useCallback: useCallback(() => {...}, [])

❌ Forgetting dependency array in useEffect
  ✓ Always include: useEffect(() => {...}, [])

❌ Not testing system preference changes
  ✓ Mock matchMedia in tests: Object.defineProperty(window, 'matchMedia', ...)

❌ Race condition: preference changes while component renders
  ✓ Store as state, update only on listener fire

OBJECTIVE:
Update authentication validation to accept special characters
in passwords (currently blocked by overly restrictive regex).

CONTEXT:
Users with passwords containing !@#$% characters cannot login.
This is a critical bug affecting ~5% of users. Fixing requires
updating validation regex to accept UTF-8 characters and adding
tests to prevent regression.

SCOPE:
Modify:
  - src/validation/password.ts (update regex)
  - src/validation/__tests__/password.test.ts (add test cases)
  - src/auth/login.ts (verify validation call)

Reference:
  - src/utils/regex.test.ts (see regex testing pattern)
  - src/auth/signup.ts (similar validation pattern)

Avoid:
  - Do NOT modify hash function
  - Do NOT change API contract
  - Do NOT modify database schema

APPROACH:
Fix password validation while maintaining security:
1. Replace current restrictive regex with Unicode-aware version
2. Ensure minimum length still enforced (8 chars)
3. Still require mix of character types (letter + number + special)
4. Add comprehensive tests for UTF-8 support

Current regex (broken):
  /^[a-zA-Z0-9!@#$%&*]+$/ (this blocks many valid special chars)

New regex (fixed):
  /^(?=.*[a-zA-Z])(?=.*[0-9])(?=.*[!@#$%&*])[\w!@#$%&*]{8,}$/
  (allows Unicode word chars + common special chars)

PATTERNS:
Pattern 1: Regex Testing
  See src/utils/regex.test.ts
  Apply: Table-driven tests for password variations
  Why: Comprehensive coverage of edge cases

Pattern 2: Validation Error Messages
  See src/validation/errors.ts
  Apply: Return specific error message per failure type
  Why: User understands exactly what's wrong

CONSTRAINTS:
- Keep error messages user-friendly
- Don't expose regex details to users
- Test with real special characters (!@#$%^&*)
- Ensure backward compatible (existing passwords still work)

BREAKING CHANGES:
None - this is a bug fix that enables previously blocked passwords.
All existing valid passwords continue to work.

SUCCESS CRITERIA:
✓ Passwords with !@#$% accepted
✓ Passwords with UTF-8 chars accepted
✓ Minimum length still enforced (8 chars)
✓ Character type mix still required
✓ Existing passwords still work
✓ Tests pass: npm test password
✓ No performance regression

COMMON MISTAKES:
❌ Making regex too permissive (security risk)
  ✓ Keep character class explicit: [\w!@#$%&*]

❌ Not escaping special chars in regex
  ✓ Use raw string or escape: \! \@ \#

❌ Forgetting test cases for boundary conditions
  ✓ Test: minimum length, maximum length, edge chars

interface SurgicalPrompt {
  // Metadata
  prompt_id: string;
  task_id: string;
  task_title: string;
  framework: string;
  language: string;
  token_estimate: number;

  // 9 Sections (breaking_changes omitted if N/A)
  sections: {
    objective: string;
    context: string;
    scope: {
      files_to_modify: string[];
      files_to_reference: string[];
      files_to_avoid: string[];
    };
    approach: string;
    patterns: Array<{
      name: string;
      source_file: string;
      how_to_apply: string;
    }>;
    constraints: Array<{
      category: string;  // "code style", "architecture", "testing", "documentation"
      rules: string[];
    }>;
    breaking_changes?: Array<{
      change: string;
      impact: string;
      migration_path: string;
    }>;
    success_criteria: string[];
    common_mistakes: Array<{
      mistake: string;
      solution: string;
    }>;
  };

  // Verification
  verification: Array<{
    step: string;
    expected_result: string;
  }>;

  // Dependencies
  task_dependencies: string[];
  blocks_tasks: string[];
}

Prompt Generation:
  - Per task: <1 minute
  - Batch (20 tasks): <15 minutes
  - Memory: <100MB per prompt

Quality:
  - Clarity score: 95%+
  - Coverage of success criteria: 100%
  - Framework guidance relevance: 90%+
  - Code examples relevance: 85%+

Efficiency:
  - Token usage tracking: 100%
  - Budget adherence: 100% (no exceeding limits)