name	pattern-discovery-capture
description	Silently capture recurring patterns discovered in the codebase during exploration. This skill logs implicit conventions, architectural patterns, and coding practices that are followed consistently but not formally documented. Use this proactively when you observe patterns that could become explicit standards.

Pattern Discovery Capture Skill

This skill helps AI agents identify and log recurring patterns discovered while exploring the codebase. The goal is to surface implicit conventions that exist in practice but aren't formally documented, enabling teams to recognize and codify their actual coding standards.

Purpose

AI agents discover patterns during codebase exploration:

"All repositories extend BaseRepository with the same methods"
"Error responses always follow { error: { code, message, details } } format"
"Use cases are always structured with execute() method returning Result"
"Tests always have a describe block per public method"
"API endpoints follow /api/v1/{resource}/{id}/{action} pattern"
"All services receive dependencies through constructor injection"

These patterns:

Represent implicit standards the team follows naturally
Are not documented in CLAUDE.md or standards files
Show actual practices (descriptive, not prescriptive)
Could become explicit standards if formalized
Help new developers understand conventions quickly

By capturing them, developers can:

Recognize conventions they follow unconsciously
Document standards that already exist in practice
Onboard faster by understanding real patterns
Ensure consistency by making implicit explicit
Build playbooks from observed best practices

When to Use This Skill

Use this skill proactively and silently during codebase exploration when you observe:

Structural Patterns
- Consistent folder organization
- Repeated file naming conventions
- Similar module structures
- Common component hierarchies
Code Patterns
- Recurring class/function structures
- Consistent method signatures
- Common error handling approaches
- Repeated validation patterns
Architectural Patterns
- Consistent layering across modules
- Repeated dependency injection patterns
- Similar API response structures
- Common data flow patterns
Testing Patterns
- Consistent test organization
- Repeated setup/teardown approaches
- Common mocking strategies
- Similar assertion patterns
Naming Conventions
- Consistent prefixes/suffixes
- Common variable naming patterns
- Repeated file naming styles
- Similar enum/constant naming

When NOT to Use

Don't capture:

Standard language idioms - TypeScript/JavaScript common patterns
Framework defaults - React, NestJS standard patterns
Single occurrences - Need 3+ examples to confirm pattern
Already documented - Patterns in CLAUDE.md or standards
Trivial patterns - Basic syntax or obvious conventions
External library patterns - Third-party API usage patterns

Workflow

Step 1: Observe Pattern (During Exploration)

While exploring the codebase, notice when multiple files/modules follow the same approach.

Step 2: Verify Pattern (3+ Examples)

Confirm the pattern appears at least 3 times to ensure it's intentional, not coincidental.

Step 3: Silent Logging

Silently append the pattern to .claude/discovered-patterns.yaml:

- timestamp: 2026-01-09T10:30:00Z
  category: 'architecture' # architecture|structure|code|testing|naming|api|error-handling|configuration
  pattern_name: 'Repository Base Class Extension'
  description: 'All domain repositories extend AbstractRepository<Entity> which provides standard CRUD operations'
  evidence:
    - file: src/domain/user/UserRepository.ts
      observation: 'extends AbstractRepository<User>'
    - file: src/domain/order/OrderRepository.ts
      observation: 'extends AbstractRepository<Order>'
    - file: src/domain/product/ProductRepository.ts
      observation: 'extends AbstractRepository<Product>'
  consistency: 'strong' # weak|moderate|strong
  coverage: 'global' # local|module|global
  formalization_value: 'high' # low|medium|high - value of making this an explicit standard
  suggested_standard: 'All domain repositories MUST extend AbstractRepository<Entity> to ensure consistent CRUD operations'
  exceptions: [] # Known deviations from this pattern
  tags:
    - 'repository-pattern'
    - 'domain-driven-design'
    - 'inheritance'

Step 3: File Management

Location: Always use .claude/discovered-patterns.yaml at the repository root.

Structure: Array of pattern entries, most recent last.

Format Rules:

timestamp: ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ)
category: One of: architecture, structure, code, testing, naming, api, error-handling, configuration
pattern_name: Short, descriptive name for the pattern
description: Clear explanation of what the pattern is
evidence: At least 3 concrete examples showing the pattern
- file: Relative path from repo root
- observation: What specifically demonstrates the pattern
consistency: How consistently the pattern is followed
- weak: 50-70% of applicable cases
- moderate: 70-90% of applicable cases
- strong: 90%+ of applicable cases
coverage: How widespread the pattern is
- local: Within specific folder/module
- module: Across related modules
- global: Throughout the codebase
formalization_value: How valuable it would be to make this explicit
- low: Nice to know, but not critical
- medium: Would help consistency
- high: Should definitely be a documented standard
suggested_standard: How this pattern could be written as an explicit rule
exceptions: Any known cases that don't follow the pattern (can be empty)
tags: Relevant keywords for filtering/searching

CRITICAL: This is a silent operation. Do NOT:

Ask the user if you should log it
Confirm to the user that you logged it
Interrupt your workflow to announce it
Make it visible in your response

Logging happens seamlessly during exploration.

Step 4: User Review (Later)

Users can review .claude/discovered-patterns.yaml at any time to:

Understand implicit conventions in their codebase
Decide which patterns to formalize as standards
Identify patterns that should be enforced
Create documentation from observed practices
Build onboarding materials for new developers

Example Scenarios

Example 1: Use Case Structure Pattern

- timestamp: 2026-01-09T09:15:00Z
  category: 'architecture'
  pattern_name: 'Use Case Execute Method Pattern'
  description: 'All use cases have a single public execute() method that takes a command/query DTO and returns Result<ResponseDTO>'
  evidence:
    - file: src/domain/user/use-cases/CreateUserUseCase.ts
      observation: 'execute(command: CreateUserCommand): Promise<Result<UserResponse>>'
    - file: src/domain/order/use-cases/PlaceOrderUseCase.ts
      observation: 'execute(command: PlaceOrderCommand): Promise<Result<OrderResponse>>'
    - file: src/domain/product/use-cases/UpdateProductUseCase.ts
      observation: 'execute(command: UpdateProductCommand): Promise<Result<ProductResponse>>'
    - file: src/domain/auth/use-cases/LoginUseCase.ts
      observation: 'execute(query: LoginQuery): Promise<Result<AuthResponse>>'
  consistency: 'strong'
  coverage: 'global'
  formalization_value: 'high'
  suggested_standard: 'Use cases MUST have a single public execute() method accepting a typed command/query DTO and returning Promise<Result<T>>'
  exceptions: []
  tags:
    - 'use-cases'
    - 'clean-architecture'
    - 'cqrs'
    - 'result-type'

Example 2: API Response Envelope Pattern

- timestamp: 2026-01-09T10:45:00Z
  category: 'api'
  pattern_name: 'API Response Envelope Structure'
  description: 'All API endpoints return responses wrapped in { data: T, meta?: { pagination } } envelope'
  evidence:
    - file: src/api/users/users.controller.ts
      observation: 'return { data: users, meta: { total, page, pageSize } }'
    - file: src/api/products/products.controller.ts
      observation: 'return { data: products, meta: { total, page, pageSize } }'
    - file: src/api/orders/orders.controller.ts
      observation: 'return { data: order } // single item, no meta'
  consistency: 'moderate'
  coverage: 'global'
  formalization_value: 'high'
  suggested_standard: 'API responses MUST use { data: T, meta?: MetaDTO } envelope. List endpoints include pagination in meta.'
  exceptions:
    - file: src/api/health/health.controller.ts
      reason: 'Health check returns { status: "ok" } directly for simplicity'
  tags:
    - 'api-design'
    - 'rest'
    - 'response-format'
    - 'pagination'

Example 3: Test File Organization Pattern

- timestamp: 2026-01-09T11:30:00Z
  category: 'testing'
  pattern_name: 'Test Describe Block per Public Method'
  description: 'Test files organize tests with a top-level describe for the class and nested describe blocks for each public method'
  evidence:
    - file: src/domain/user/User.spec.ts
      observation: 'describe("User") > describe("create") > describe("update") > describe("delete")'
    - file: src/services/auth/AuthService.spec.ts
      observation: 'describe("AuthService") > describe("login") > describe("logout") > describe("refresh")'
    - file: src/domain/order/OrderProcessor.spec.ts
      observation: 'describe("OrderProcessor") > describe("process") > describe("cancel") > describe("refund")'
  consistency: 'strong'
  coverage: 'global'
  formalization_value: 'medium'
  suggested_standard: 'Test files MUST have top-level describe for the class/module and nested describe blocks for each public method being tested'
  exceptions: []
  tags:
    - 'testing'
    - 'test-organization'
    - 'describe-blocks'

Example 4: Error Class Hierarchy Pattern

- timestamp: 2026-01-09T14:00:00Z
  category: 'error-handling'
  pattern_name: 'Domain Error Class Hierarchy'
  description: 'All domain errors extend DomainError base class with code, message, and optional details'
  evidence:
    - file: src/domain/errors/UserNotFoundError.ts
      observation: 'extends DomainError { code = "USER_NOT_FOUND" }'
    - file: src/domain/errors/InsufficientFundsError.ts
      observation: 'extends DomainError { code = "INSUFFICIENT_FUNDS" }'
    - file: src/domain/errors/InvalidOrderStateError.ts
      observation: 'extends DomainError { code = "INVALID_ORDER_STATE" }'
    - file: src/domain/errors/DuplicateEmailError.ts
      observation: 'extends DomainError { code = "DUPLICATE_EMAIL" }'
  consistency: 'strong'
  coverage: 'module'
  formalization_value: 'high'
  suggested_standard: 'Domain errors MUST extend DomainError and define a unique error code in SCREAMING_SNAKE_CASE'
  exceptions: []
  tags:
    - 'error-handling'
    - 'domain-errors'
    - 'inheritance'
    - 'error-codes'

Example 5: Component Props Interface Pattern

- timestamp: 2026-01-09T15:20:00Z
  category: 'naming'
  pattern_name: 'Component Props Interface Naming'
  description: 'React component props interfaces are named {ComponentName}Props and defined directly above the component'
  evidence:
    - file: src/components/Button/Button.tsx
      observation: 'interface ButtonProps { ... } export const Button = (props: ButtonProps)'
    - file: src/components/Modal/Modal.tsx
      observation: 'interface ModalProps { ... } export const Modal = (props: ModalProps)'
    - file: src/components/Card/Card.tsx
      observation: 'interface CardProps { ... } export const Card = (props: CardProps)'
  consistency: 'strong'
  coverage: 'global'
  formalization_value: 'medium'
  suggested_standard: 'React component props interfaces MUST be named {ComponentName}Props and defined directly above the component export'
  exceptions: []
  tags:
    - 'react'
    - 'typescript'
    - 'props'
    - 'naming-convention'

Example 6: Service Constructor Injection Pattern

- timestamp: 2026-01-09T16:10:00Z
  category: 'architecture'
  pattern_name: 'Constructor Dependency Injection'
  description: 'All services receive dependencies through constructor injection with private readonly parameters'
  evidence:
    - file: src/services/user/UserService.ts
      observation: 'constructor(private readonly userRepo: IUserRepository, private readonly emailService: IEmailService)'
    - file: src/services/order/OrderService.ts
      observation: 'constructor(private readonly orderRepo: IOrderRepository, private readonly paymentGateway: IPaymentGateway)'
    - file: src/services/notification/NotificationService.ts
      observation: 'constructor(private readonly emailService: IEmailService, private readonly smsService: ISmsService)'
  consistency: 'strong'
  coverage: 'global'
  formalization_value: 'high'
  suggested_standard: 'Services MUST receive dependencies through constructor injection using private readonly parameters typed with interfaces'
  exceptions: []
  tags:
    - 'dependency-injection'
    - 'constructor-injection'
    - 'services'
    - 'solid-principles'

Integration Pattern

During Exploration

While exploring the codebase:

Read multiple files in similar categories
Notice when they share common structures/approaches
Verify pattern exists in 3+ files
Silently log the discovered pattern
Continue exploration

Example Flow

User: "Help me understand how repositories work in this codebase"

[AI explores src/domain/user/UserRepository.ts]
[AI explores src/domain/order/OrderRepository.ts]
[AI explores src/domain/product/ProductRepository.ts]
[AI thinking: "All extend AbstractRepository - consistent pattern"]
[AI thinking: "All have same method signatures - confirmed pattern"]

[AI silently logs pattern to .claude/discovered-patterns.yaml]

AI: "Repositories in this codebase follow a consistent pattern:
     - All extend AbstractRepository<Entity>
     - Provides standard findById, findAll, save, delete methods
     - Custom queries are added as additional methods..."

User sees the explanation. Later, they can review discovered-patterns.yaml to formalize this as a standard.

Benefits

Pattern Recognition: Surfaces implicit conventions teams follow
Standard Creation: Provides basis for explicit standards
Onboarding: Helps new developers understand real practices
Consistency: Makes implicit patterns explicit and enforceable
Documentation: Auto-generates convention documentation
Quality: Identifies practices worth preserving

Important Guidelines

Require evidence: Minimum 3 examples before logging pattern
Be specific: Pattern should be concrete and actionable
Be accurate: Only log patterns actually observed
Be silent: Never interrupt workflow with logging notifications
Suggest standards: Always include how this could be formalized
Note exceptions: Document known deviations honestly
Assess value: Not all patterns need to become standards
Track consistency: Weak patterns may not be worth formalizing

Discovered Patterns YAML Schema

# .claude/discovered-patterns.yaml
- timestamp: string           # ISO 8601: "2026-01-09T10:30:00Z"
  category: string            # architecture|structure|code|testing|naming|api|error-handling|configuration
  pattern_name: string        # Short name: "Repository Base Class Extension"
  description: string         # What the pattern is
  evidence: array            # At least 3 examples
    - file: string           # Relative path
      observation: string    # What demonstrates the pattern
  consistency: string        # weak|moderate|strong
  coverage: string           # local|module|global
  formalization_value: string # low|medium|high
  suggested_standard: string  # How to write as explicit rule
  exceptions: array          # Known deviations (can be empty)
    - file: string
      reason: string
  tags: array               # Keywords
    - string

Future Use

Once .claude/discovered-patterns.yaml accumulates entries, developers can:

Review by value - Prioritize high-formalization-value patterns
Create standards - Use signal-capture to formalize patterns
Build documentation - Generate "How We Code" guides
Enforce consistency - Add linting rules based on patterns
Onboard developers - Share patterns during onboarding
Track evolution - See how patterns emerge and change
Identify gaps - Find areas without consistent patterns

Integration with Other Skills

signal-capture: Formalize discovered patterns as standards

Pattern discovered → Team approves → Use signal-capture to add standard

consistency-violation-capture: Patterns help identify violations

Pattern: "All repos extend AbstractRepository"
Violation: "NewRepo doesn't extend AbstractRepository"

implicit-decision-capture: Decisions may follow discovered patterns

Pattern: "Use Result types for errors"
Decision: "Used Result type in new service (following pattern)"

Distinction from Other Captures

Pattern Discovery: "The codebase does X" (observation)
Consistency Violation: "Part A does X, part B does Y" (conflict)
Decision Capture: "I chose to do X" (choice made)
Signal Capture: "User wants X as standard" (explicit preference)

Pattern discovery is descriptive (what IS done), while standards are prescriptive (what SHOULD be done). Discovered patterns can become standards through formalization.

Remember: This skill should be used proactively and silently during codebase exploration. It's not about asking permission - it's about surfacing implicit conventions that could become explicit standards.

pattern-discovery-capture

Install Skill

SKILL.md