pattern-analysis

name	pattern-analysis
department	craftsman
description	Use when auditing codebase patterns or evaluating proposed changes for convention consistency. Covers file naming, component patterns, data fetching, state management, and type conventions. Do not use for test plan design or coverage targets (use testing-strategy).
version	1
triggers	["pattern","convention","consistency","refactor","code quality","style","architecture","anti-pattern","code review","DX"]

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