dtsong/pattern-analysis

Pattern Analysis

Purpose

Audit the codebase for existing patterns and conventions, then evaluate proposed changes for consistency.

Scope Constraints

• Covers file naming, directory structure, component patterns, data fetching, state management, error handling, and type conventions.
• Does not cover test strategy design or coverage targets — hand off to testing-strategy.
• Does not cover high-level architectural decisions or system decomposition — hand off to architect department.

Inputs

• Codebase or directory to audit
• Proposed changes or new code to evaluate (if applicable)
• Specific concerns or areas of focus (if any)
• Known tech stack and framework conventions

Input Sanitization

No user-provided values are used in commands or file paths. All inputs are treated as read-only analysis targets.

Procedure

Step 1: Scan Structural Patterns

• File naming conventions:
  • kebab-case, PascalCase, camelCase, snake_case
  • Suffix conventions (.utils.ts, .types.ts, .test.ts, .stories.tsx)
• Directory organization:
  • Feature-based (feature/components, feature/hooks, feature/utils)
  • Layer-based (components/, hooks/, utils/, types/)
  • Hybrid approaches
• Module export patterns:
  • Barrel files (index.ts re-exports)
  • Direct imports
  • Default vs named exports

Step 2: Identify Code Patterns

• Component patterns:
  • Server vs client components (React Server Components)
  • Composition patterns (render props, compound components, HOCs)
  • Prop drilling vs context vs stores
• Data fetching patterns:
  • Custom hooks (useQuery, useSWR, custom fetch hooks)
  • Server actions
  • API routes
  • Direct fetch in server components
• State management patterns:
  • Local state (useState, useReducer)
  • Context (React Context, providers)
  • External stores (Zustand, Jotai, Redux)
  • URL state (search params, pathname)
• Error handling patterns:
  • try/catch blocks
  • Result/Either types
  • Error boundaries
  • Toast notifications
• Type patterns:
  • interfaces vs type aliases
  • Generic patterns and utility types
  • Zod schemas vs manual types
  • Shared type files vs co-located types

Step 3: Catalog Existing Conventions

Document discovered conventions:

| Category | Convention | Example File | Frequency | |----------|-----------|--------------|-----------| | File naming | ... | ... | ... | | Component style | ... | ... | ... | | Data fetching | ... | ... | ... | | State management | ... | ... | ... | | Error handling | ... | ... | ... | | Type definitions | ... | ... | ... | | Import ordering | ... | ... | ... | | Comment style | ... | ... | ... | | Testing patterns | ... | ... | ... |

Step 4: Evaluate Proposed Changes

For each proposed change, check:

• Does it follow existing naming conventions? (files, variables, functions, components)
• Does it follow existing structural patterns? (directory placement, export style)
• Does it reuse existing utilities/helpers? (don't reinvent what exists)
• Does it introduce a new pattern? If so:
  • Is the new pattern justified? (existing pattern inadequate, new requirement)
  • Is it better enough to warrant migration? Or just different?
  • Will it cause confusion having two patterns for the same thing?
• Does it create inconsistency with similar existing code? (same feature, neighboring files)

Step 5: Produce Recommendations

• Follow these patterns (with file references as examples):
  • Pattern A: See src/components/ExampleComponent.tsx
  • Pattern B: See src/hooks/useExampleHook.ts
• Avoid these patterns (with rationale):
  • Anti-pattern X: Because [reason]
  • Deprecated pattern Y: Replaced by [alternative]
• Consider refactoring (if new patterns are genuinely better):
  • Migrate pattern A to pattern B across [scope]
  • Estimated scope: [number of files affected]

Compaction resilience: If context is compacted mid-task, re-read this Procedure section and continue from the next incomplete step.

Handoff

• If the pattern audit reveals test convention inconsistencies or missing test coverage, hand off to testing-strategy for a comprehensive test plan.
• If patterns suggest deeper architectural issues such as unclear module boundaries or circular dependencies, hand off to architect department for structural analysis.

Output Format

Pattern Inventory

| Category | Pattern | Example File | Frequency | Status | |----------|---------|--------------|-----------|--------| | File naming | kebab-case components | src/components/team-card.tsx | High | Standard | | Data fetching | useQuery hooks | src/hooks/use-teams.ts | High | Standard | | ... | ... | ... | ... | ... |

Consistency Report

| Proposed Change | Existing Pattern | Match? | Recommendation | |----------------|-----------------|--------|----------------| | ... | ... | Yes/No | ... |

Recommendations

1. Follow: [pattern] — see [file reference]
2. Avoid: [anti-pattern] — because [rationale]
3. Refactor: [migration suggestion] — [scope and effort]

Quality Checks

• [ ] At least 3 file/code categories audited (naming, structure, data fetching, state, errors)
• [ ] Naming conventions documented with examples
• [ ] Data fetching pattern identified and documented
• [ ] State management pattern identified and documented
• [ ] New code evaluated against each discovered pattern
• [ ] Example files referenced for each pattern
• [ ] Anti-patterns identified with rationale
• [ ] Recommendations are actionable (not vague)

Evolution Notes

<!-- Observations appended after each use -->