/does-this-clash

Using @agent-mentor analyze whether specific code aligns with established codebase patterns, conventions, and architectural principles.

Input Parsing

The user invoked: /does-this-clash {code_reference}

Examples:

• /does-this-clash src/services/new-feature.ts - Check if new code fits patterns
• /does-this-clash PR #123 - Review PR for pattern consistency
• /does-this-clash this commit - Check recent changes
• /does-this-clash - Interactive mode to identify what to check

Your Task

This is a pattern consistency analysis, not subjective taste critique. The goal is to help developers write code that fits naturally into the existing codebase by identifying where their code diverges from established conventions.

Core Philosophy

Focus on observable patterns, not opinions. This tool:

• Compares code against documented or repeated patterns in the codebase
• Identifies inconsistencies that might confuse future maintainers
• Teaches codebase conventions through concrete examples
• Invites discussion when violations might be intentional

This is NOT about "right" vs "wrong" - it's about consistency vs. divergence, and helping developers understand the existing patterns before they choose to diverge from them.

1. Identify What to Analyze

Determine:

• What code needs consistency checking (file, module, PR, commit)
• What kind of code is it (service, component, utility, test, config)
• What is it trying to accomplish (feature, fix, refactor)
• Is this a new pattern or fitting into existing patterns

If unclear, ask:

• "What code would you like me to check for consistency?"
• "Is this new code you're writing or existing code you're reviewing?"
• "Are you trying to match existing patterns or introduce a new one?"

2. Pattern Discovery Phase

Map the existing patterns in the codebase:

Architectural Patterns

Identify the established architecture:

# What's the folder structure convention?
tree src/ -L 2 -d

# Where do similar things live?
find . -name "*Service.ts" -o -name "*Controller.ts" -o -name "*Repository.ts"

# What's the layering pattern?
# Controllers -> Services -> Repositories?
# Features -> Domain -> Infrastructure?

Questions to answer:

• How is the codebase organized (by feature, by layer, hybrid)?
• What goes in which folder?
• How do layers interact?
• What's the dependency flow?

Code Style Patterns

Naming Conventions:

# What naming style is used?
grep -r "^class \|^function \|^const \|^interface " src/ | head -20

# Variable naming patterns
# camelCase? snake_case? PascalCase?
# Descriptive names? Abbreviations? Prefixes?

File Naming:

# How are files named?
ls src/**/*.ts | head -20

# kebab-case? camelCase? PascalCase?
# .service.ts? Service.ts? -service.ts?

Function/Method Patterns:

• Async everywhere or mixed?
• Arrow functions or function declarations?
• Return types explicit or inferred?
• Early returns or nested ifs?

Error Handling Patterns

How does the codebase handle errors?

# Exceptions or error returns?
grep -r "throw new" src/ | head -10
grep -r "return.*Error\|Result<" src/ | head -10

# Try-catch patterns
grep -r "try {" src/ -A 5 | head -20

# Error types
grep -r "class.*Error extends" src/

Common patterns:

• Throws exceptions vs. returns Result types
• Custom error classes vs. built-in Error
• Error handling at boundaries vs. propagation
• Logging patterns for errors

Dependency Management Patterns

How are dependencies handled?

# Dependency injection?
grep -r "constructor.*inject\|@Inject" src/ | head -10

# Service locator?
grep -r "Container.get\|ServiceLocator" src/ | head -10

# Direct imports?
grep -r "import.*Service.*from" src/ | head -10

Common patterns:

• Constructor injection
• Property injection
• Service locator pattern
• Factory patterns
• Singleton patterns

Data Access Patterns

How does code talk to data?

# ORM usage
grep -r "Repository\|Entity\|@Column" src/ | head -10

# Raw SQL
grep -r "SELECT \|query(.*SELECT\|sql\`" src/ | head -10

# Query builders
grep -r "\.where(.*\.select(" src/ | head -10

Common patterns:

• ORM (TypeORM, Prisma, Sequelize)
• Query builders (Knex, Kysely)
• Raw SQL with parameters
• Repository pattern

Testing Patterns

How are tests structured?

# Test file naming
ls **/*.test.* **/*.spec.* | head -10

# Test structure
grep -r "describe(.*it(" tests/ | head -20

# Mocking patterns
grep -r "jest.mock\|sinon\|vi.mock" tests/ | head -10

Common patterns:

• describe/it vs. test()
• beforeEach patterns
• Mock strategy (jest, sinon, vitest)
• Test data setup
• Assertion style (expect, assert, should)

API/Interface Patterns

How are interfaces designed?

# REST conventions
grep -r "router\.\(get\|post\|put\|delete\)" src/ | head -20

# GraphQL patterns
grep -r "type Query\|type Mutation" src/ | head -10

# Internal APIs
grep -r "export.*function\|export.*class" src/ | head -20

Common patterns:

• RESTful conventions
• GraphQL schema design
• RPC patterns
• Function signatures (options object vs. multiple params)

State Management Patterns

How is state handled?

# State libraries
grep -r "useState\|createStore\|atom\|signal" src/ | head -10

# State mutation patterns
grep -r "\.setState\|state\.\w+\s*=" src/ | head -10

Common patterns:

• Immutable updates
• Mutable state
• Redux/Zustand/Jotai patterns
• React context usage

3. Consistency Analysis

Compare the target code against discovered patterns:

Pattern Alignment Checklist

For each pattern category, identify:

✅ Aligned (Follows Pattern):

• Uses same naming conventions
• Matches folder structure
• Follows architectural layers
• Uses established error handling
• Matches testing style

⚠️ Divergent (Different Approach):

• Uses different naming style
• Located in unexpected place
• Breaks architectural boundaries
• Different error handling
• Inconsistent with similar code

❌ Contradictory (Conflicts with Pattern):

• Violates established boundaries
• Breaks dependency rules
• Introduces incompatible pattern
• Creates confusion with existing code

4. Context Investigation

Before flagging divergence, investigate if there's a reason:

Check for intentional pattern evolution:

# Is this part of a migration?
git log --grep="migrate\|refactor\|modernize" -- {file}

# Are similar recent changes using new pattern?
git log --since="3 months ago" --oneline -- src/{area}/ | head -20

# Is there a TODO or ADR about this?
grep -r "TODO.*migrate\|FIXME.*update" . --include="*.md"

Look for external constraints:

• Library requirements (GraphQL might dictate structure)
• Framework conventions (Next.js, Nest.js patterns)
• External API contracts (must match third-party format)
• Performance requirements (unusual pattern for speed)

Check for similar code:

# Is this actually following a subset pattern?
grep -r "similar-pattern" src/{other-area}/

5. Save Output

Create a markdown file at /reports/pattern-consistency-{scope}-{timestamp}.md with the analysis.

Output Format

# Pattern Consistency Analysis: [Code Reference]

## What Was Analyzed
**Scope**: [File/Module/PR being checked]
**Type**: [Service/Component/Util/Test/etc.]
**Purpose**: [What this code does]
**Context**: [New feature / Bug fix / Refactor / etc.]

## Summary
**Overall Consistency**: ✅ Well-aligned / ⚠️ Some divergence / ❌ Significant conflicts

**Key Findings:**
- [Most important observation]
- [Second most important observation]
- [Third observation if relevant]

**TL;DR**: [One sentence assessment]

---

## Established Codebase Patterns

### Architectural Organization
**Pattern**: [How the codebase is organized]

src/ ├── features/ # Feature-based organization │ ├── auth/ │ ├── users/ │ └── billing/ ├── shared/ # Shared utilities └── infrastructure/ # External concerns

**Principle**: Features are self-contained, shared code is minimal

**Examples**: `src/features/auth/`, `src/features/users/`

### Naming Conventions
**Pattern**: [Established naming style]

- **Files**: `kebab-case.ts` (e.g., `user-service.ts`, `auth-controller.ts`)
- **Classes**: `PascalCase` (e.g., `UserService`, `AuthController`)
- **Functions**: `camelCase` (e.g., `validateUser`, `createSession`)
- **Constants**: `UPPER_SNAKE_CASE` (e.g., `MAX_RETRIES`, `API_TIMEOUT`)
- **Interfaces**: `PascalCase` with descriptive names (e.g., `UserRepository`, `AuthConfig`)

**Examples**:
- `src/features/auth/auth-service.ts` exports `AuthService` class
- `src/shared/utils/string-helpers.ts` exports `camelCase` functions

### Error Handling
**Pattern**: [How errors are handled]

**Approach**: Custom error classes + try-catch at boundaries

```typescript
// Custom errors for domain problems
class UserNotFoundError extends Error {
  constructor(userId: string) {
    super(`User ${userId} not found`);
  }
}

// Try-catch at controller boundaries
async handleRequest(req, res) {
  try {
    const result = await service.process(req.body);
    res.json(result);
  } catch (error) {
    if (error instanceof UserNotFoundError) {
      res.status(404).json({ error: error.message });
    } else {
      logger.error(error);
      res.status(500).json({ error: "Internal error" });
    }
  }
}

// Services throw, controllers catch

Examples: src/features/auth/errors.ts, src/shared/middleware/error-handler.ts

Why this pattern: Exceptions for exceptional cases, caught at boundaries, logged centrally

Dependency Management

Pattern: [How dependencies are injected]

Approach: Constructor injection with interfaces

interface UserRepository {
  findById(id: string): Promise<User | null>;
}

class UserService {
  constructor(private userRepo: UserRepository) {}

  async getUser(id: string): Promise<User> {
    const user = await this.userRepo.findById(id);
    if (!user) throw new UserNotFoundError(id);
    return user;
  }
}

Examples: src/features/users/user-service.ts

Why this pattern: Testability, loose coupling, clear dependencies

Data Access

Pattern: [How data is accessed]

Approach: Repository pattern with Prisma ORM

class UserRepository {
  constructor(private db: PrismaClient) {}

  async findById(id: string): Promise<User | null> {
    return this.db.user.findUnique({ where: { id } });
  }
}

Not used: Raw SQL, query builders (except for complex reporting queries)

Examples: src/features/users/user-repository.ts

Why this pattern: Type safety, consistent API, easy testing

Testing Patterns

Pattern: [How tests are structured]

Approach: Jest with describe/it, mocks for external dependencies

describe('UserService', () => {
  let service: UserService;
  let mockRepo: jest.Mocked<UserRepository>;

  beforeEach(() => {
    mockRepo = {
      findById: jest.fn(),
    };
    service = new UserService(mockRepo);
  });

  it('should throw when user not found', async () => {
    mockRepo.findById.mockResolvedValue(null);

    await expect(service.getUser('123'))
      .rejects
      .toThrow(UserNotFoundError);
  });
});

Examples: src/features/users/__tests__/user-service.test.ts

Why this pattern: Clear structure, isolated tests, easy to read

API Design

Pattern: [How APIs are structured]

Approach: RESTful with resource-based routes

router.get('/users/:id', userController.getUser);
router.post('/users', userController.createUser);
router.put('/users/:id', userController.updateUser);
router.delete('/users/:id', userController.deleteUser);

Response format: JSON with consistent shape

// Success
{ data: { /* resource */ } }

// Error
{ error: { message: string, code?: string } }

Examples: src/features/users/user-routes.ts

---

Your Code Analysis

Architectural Alignment

✅ Follows Pattern: File Organization

Your code is in src/features/billing/billing-service.ts

Why this is good: Follows feature-based organization, billing is clearly a feature

Pattern match: Same structure as auth/ and users/ features

⚠️ Diverges from Pattern: Layer Boundary

Your code: BillingService directly imports from src/infrastructure/database/prisma

Established pattern: Services use Repository abstractions, not direct DB access

Examples of pattern:

// Established pattern (from UserService)
class UserService {
  constructor(private userRepo: UserRepository) {} // ← Repository abstraction
}

// Your code
class BillingService {
  constructor(private db: PrismaClient) {} // ← Direct DB access
}

Why this matters:

• Breaks architectural layering
• Makes testing harder (must mock PrismaClient)
• Couples service to specific ORM
• Inconsistent with rest of codebase

Found in: src/features/billing/billing-service.ts:12

How to align:

// Create repository abstraction
interface BillingRepository {
  findInvoice(id: string): Promise<Invoice | null>;
  saveInvoice(invoice: Invoice): Promise<void>;
}

class BillingService {
  constructor(private billingRepo: BillingRepository) {} // ← Matches pattern
}

Counterpoint to consider: Is billing-specific query complexity why you chose direct access? If so, document this decision and consider if the trade-off is worth the inconsistency.

Naming Consistency

✅ Follows Pattern: Class Names

BillingService uses PascalCase, matches pattern

✅ Follows Pattern: File Names

billing-service.ts uses kebab-case, matches pattern

⚠️ Diverges from Pattern: Function Names

Established pattern: Descriptive verb-noun (e.g., createUser, validateToken)

Your code: Abbreviated names (e.g., procInv, calcTtl)

Examples of divergence:

// Established pattern
async function validateUser(userId: string): Promise<boolean>
async function createSession(user: User): Promise<Session>

// Your code
async function procInv(inv: Invoice): Promise<void>  // ← Abbreviated
async function calcTtl(items: Item[]): Promise<number>  // ← Abbreviated

Why this matters:

• Harder to understand without context
• Inconsistent with codebase style
• No character limit reason for abbreviation

How to align:

async function processInvoice(invoice: Invoice): Promise<void>
async function calculateTotal(items: Item[]): Promise<number>

Error Handling Alignment

❌ Conflicts with Pattern: Error Strategy

Established pattern: Throw custom error classes

Your code: Returns null or undefined on errors

Examples of conflict:

// Established pattern (from UserService)
async function getUser(id: string): Promise<User> {
  const user = await repo.findById(id);
  if (!user) throw new UserNotFoundError(id); // ← Throws custom error
  return user;
}

// Your code (from BillingService)
async function getInvoice(id: string): Promise<Invoice | null> {
  const invoice = await db.invoice.findUnique({ where: { id } });
  return invoice; // ← Returns null on not found
}

Why this matters:

• Callers must handle null checks
• Inconsistent error handling across codebase
• Loses error context (why was it null?)
• Forces defensive programming everywhere

How to align:

class InvoiceNotFoundError extends Error {
  constructor(invoiceId: string) {
    super(`Invoice ${invoiceId} not found`);
  }
}

async function getInvoice(id: string): Promise<Invoice> {
  const invoice = await repo.findById(id);
  if (!invoice) throw new InvoiceNotFoundError(id);
  return invoice;
}

Found in: src/features/billing/billing-service.ts:45, :67, :89

Dependency Management

✅ Follows Pattern: Constructor Injection

Your code uses constructor injection consistently

Testing Alignment

⚠️ Diverges from Pattern: Test Structure

Established pattern: Jest with describe/it nesting, beforeEach setup

Your code: Flat test() calls, setup in each test

Examples of divergence:

// Established pattern
describe('UserService', () => {
  let service: UserService;

  beforeEach(() => {
    service = new UserService(mockRepo);
  });

  it('should create user', async () => { /* ... */ });
  it('should validate email', async () => { /* ... */ });
});

// Your code
test('create invoice works', async () => {
  const service = new BillingService(mockDb); // ← Setup in each test
  /* ... */
});

test('calculate total works', async () => {
  const service = new BillingService(mockDb); // ← Duplicate setup
  /* ... */
});

Why this matters:

• Less organized, harder to read
• Duplicate setup code
• Doesn't group related tests
• Inconsistent with 47 other test files

How to align: Use describe/it structure with beforeEach

Found in: src/features/billing/__tests__/billing-service.test.ts

---

Pattern Summary

Alignment Score: 6/10

Aligned (4 areas):

• ✅ File organization
• ✅ Class naming
• ✅ File naming
• ✅ Constructor injection

Divergent (3 areas):

• ⚠️ Layer boundaries (direct DB vs. repository)
• ⚠️ Function naming (abbreviated vs. descriptive)
• ⚠️ Test structure (flat vs. nested)

Conflicting (1 area):

• ❌ Error handling (null returns vs. throwing)

Impact Assessment

High Impact (Fix Soon):

1. Error handling strategy - Inconsistent across codebase, affects all callers
2. Layer boundaries - Breaks architecture, affects testing and maintainability

Medium Impact (Should Fix): 3. Function naming - Readability and consistency matter 4. Test structure - Maintainability and consistency

Low Impact (Nice to Have): None identified

---

Recommendations

Priority 1: Error Handling Consistency

Change from:

async function getInvoice(id: string): Promise<Invoice | null> {
  return await db.invoice.findUnique({ where: { id } });
}

Change to:

async function getInvoice(id: string): Promise<Invoice> {
  const invoice = await repo.findById(id);
  if (!invoice) throw new InvoiceNotFoundError(id);
  return invoice;
}

Why: Matches established pattern, makes errors explicit, consistent with 23 other services

Files to update: billing-service.ts:45, :67, :89

Priority 2: Repository Abstraction

Create: BillingRepository interface + implementation

Change from:

class BillingService {
  constructor(private db: PrismaClient) {}
}

Change to:

class BillingService {
  constructor(private billingRepo: BillingRepository) {}
}

Why: Matches layering pattern, improves testability, consistent with UserService, AuthService, etc.

Files to create: billing-repository.ts, billing-repository.test.ts

Priority 3: Function Naming

Expand abbreviated names:

• procInv → processInvoice
• calcTtl → calculateTotal
• genRpt → generateReport

Why: Readability, consistency with 200+ other descriptive function names

Files to update: billing-service.ts (8 functions)

Priority 4: Test Structure

Refactor tests to use describe/it with beforeEach setup

Why: Consistency with 47 other test files, better organization

Files to update: billing-service.test.ts

---

Questions to Consider

These aren't criticisms - they're genuine questions to help you think through the trade-offs:

On Repository Abstraction

Q: Did you skip the repository layer for a specific reason?

• Is there complex billing-specific SQL that makes abstraction awkward?
• Are you planning to add it later?
• Is this a different architectural pattern you're introducing?

If intentional: Consider documenting why billing is different, or this becomes confusing

If not intentional: Aligning with the pattern would help maintainability

On Error Handling

Q: What's the advantage of null returns over throwing errors in your use case?

• Are callers checking for null anyway?
• Is there a performance concern with exceptions?
• Is this coming from a different language background (Go, C)?

Consider: The codebase uses exceptions consistently - null checks would be needed everywhere in your code

On Naming

Q: Is there a character limit or verbosity concern?

• Are these names used so frequently that brevity helps?
• Is this matching an external API or spec?

Consider: Most function names in the codebase are fully spelled out

---

If You Choose to Diverge

That's totally valid! Sometimes new patterns are better than established ones.

If you're intentionally introducing a different approach:

1. Document why - Add comments or ADR explaining the decision
2. Be consistent within your module - If you're using null returns, use them everywhere in billing
3. Consider scope - Is this just billing, or are you proposing a codebase-wide change?
4. Discuss with team - New patterns should be intentional, not accidental

Example documentation:

/**
 * Billing module uses null returns instead of exceptions for not-found cases
 * to match the payment provider API semantics. See ADR-023 for rationale.
 */

---

Learning Takeaways

About Pattern Consistency

Why it matters:

• Reduces cognitive load (code looks familiar)
• Easier onboarding (patterns are predictable)
• Better maintainability (know where to look)
• Less friction in code review

It's not about "right" vs "wrong":

• Established patterns aren't always optimal
• But consistency has value even if pattern is imperfect
• Changing patterns should be intentional, not accidental

About Codebase Conventions

How to discover patterns:

• Look at multiple examples of similar code
• Check for repeated structures
• Read documentation and READMEs
• Ask: "How do other parts do this?"

When to follow vs. diverge:

• Follow by default - Consistency is valuable
• Diverge with reason - Document why
• Propose changes - If pattern is genuinely bad, change it everywhere

Pattern Recognition Skills

As you work in codebases, you'll develop intuition for:

• "This feels different from the rest"
• "I've seen this pattern before"
• "This is how we do X here"

This analysis helps build that intuition explicitly.

---

Next Steps

Quick Consistency Wins (< 1 hour)

• Rename abbreviated functions
• Adjust test structure to match pattern

Architectural Alignment (2-3 hours)

• Create BillingRepository interface
• Implement repository
• Update BillingService to use repository
• Update tests

Error Handling Consistency (1 hour)

• Create custom error classes
• Replace null returns with exceptions
• Update tests for new error handling

If Diverging Intentionally

• Document rationale
• Be consistent within module
• Discuss with team
• Consider scope (module vs. codebase)

---

Related Commands

• /why-this-way [pattern] - Understand why existing patterns exist
• /explain [code] - Deep dive into how something works
• /what-would-break [change] - Understand impact of changing patterns

---

Analysis completed: [timestamp] Patterns analyzed: [count] Files compared: [count] Similar code examined: [count examples]

Remember: Consistency is valuable, but not sacred. This analysis helps you make informed decisions about when to follow patterns and when to diverge from them. The goal is intentional code, not blind conformity.

## Investigation Techniques

### Pattern Discovery Methods

**Statistical Analysis:**
```bash
# Count pattern occurrences to establish "established"
grep -r "class.*Service" src/ | wc -l  # 23 services
grep -r "throw new.*Error" src/ | wc -l  # 145 throws
grep -r "return null" src/ | wc -l  # 12 null returns

# If 23 services use pattern A and 1 uses pattern B, A is established

Find Representative Examples:

# Find the most similar code to what's being checked
# If checking a service, find other services
find src/features -name "*-service.ts" | head -5

# If checking tests, find similar tests
find . -name "*.test.ts" -path "*/features/*" | head -5

Architectural Layering:

# Map import patterns to understand layers
grep -r "^import.*from" src/features/users/ | \
  sed 's/.*from "\(.*\)".*/\1/' | \
  sort | uniq -c | sort -rn

# See what each layer imports
# Controllers import Services?
# Services import Repositories?
# Repositories import Database?

Convention Documentation:

# Check for explicit conventions
cat CONTRIBUTING.md docs/STYLE_GUIDE.md README.md

# Check for linter rules (explicit conventions)
cat .eslintrc.json .prettierrc

# Check for architectural decision records
find . -name "*.md" -path "*/adr/*"

Context Detection

Check for Migration in Progress:

# Recent commits changing patterns
git log --since="6 months ago" --grep="refactor\|migrate" --oneline

# Mixed old/new patterns suggest transition
git log --all --oneline -- src/features/*/new-pattern.ts

Check for External Requirements:

# Framework requirements
cat package.json | grep -E "next|nest|express"

# Library patterns
grep -r "@nestjs/common" src/ # NestJS has opinions
grep -r "from 'next" src/ # Next.js has conventions

Comparing Code Effectively

Side-by-Side Pattern Comparison:

Always show:

1. The established pattern (with file reference)
2. The code being checked
3. The specific difference
4. Why the difference matters

Example:

// Established pattern (from user-service.ts:23)
async function getUser(id: string): Promise<User> {
  const user = await this.repo.findById(id);
  if (!user) throw new UserNotFoundError(id);
  return user;
}

// Your code (from billing-service.ts:45)
async function getInvoice(id: string): Promise<Invoice | null> {
  return await this.db.invoice.findUnique({ where: { id } });
}

// Difference: null return vs. exception throw
// Why it matters: Inconsistent error handling, callers must handle differently

Educational Approach

Frame as Learning, Not Criticism

DO:

• "The established pattern is X, here's where it's used"
• "This differs from the pattern in Y way"
• "Here's why the pattern exists"
• "Here's how to align, if you choose to"

DON'T:

• "You did this wrong"
• "This violates best practices"
• "You should always do X"
• Present as absolute rules

Always Provide Context

For every divergence, explain:

1. What the established pattern is
2. Where it's used (file references)
3. How the code differs
4. Why the pattern exists
5. How to align (if desired)
6. When divergence might be valid

Invite Discussion

Include questions like:

• "Did you skip X for a specific reason?"
• "Is this matching an external requirement?"
• "Are you proposing a new pattern?"
• "Is there context I'm missing?"

Recognize Valid Reasons to Diverge

Valid reasons:

• External API requirements
• Performance constraints
• Library requirements
• Intentional pattern evolution
• Domain-specific needs

Invalid reasons:

• Didn't know the pattern
• Copied from elsewhere
• Personal preference without discussion
• Accidental inconsistency

Teach Pattern Recognition

Include sections like:

### How to Discover Patterns Yourself

1. Look at multiple similar examples
2. Count occurrences (1 instance ≠ pattern)
3. Check documentation
4. Look for repeated structures
5. Ask: "How do other parts do this?"

### Building Pattern Intuition

As you read code, ask:
- "Is this the only place that does it this way?"
- "Does this feel different from similar code?"
- "Are the same concerns handled differently elsewhere?"

Response Templates

When Code Matches Well

Good news! Your code aligns well with established patterns.

**Alignment: 9/10**

✅ Matches architectural structure
✅ Follows naming conventions
✅ Uses established error handling
✅ Consistent testing approach

**Minor observations:**
- [One small thing if any]

**Teaching moment:** You've clearly studied the codebase patterns. This code will feel natural to maintainers.

[Save brief report]

When Code Has Some Divergence

Your code is mostly aligned with a few areas of divergence from established patterns.

**Alignment: 6/10**

Let me show you the patterns and where your code differs:

[Detailed analysis of patterns and divergences]

**High priority:**
- [Most important divergence to address]

**Medium priority:**
- [Less critical divergences]

**Teaching moment:** [Explain why patterns matter and how to discover them]

[Save detailed report]

When Code Conflicts Significantly

Your code takes a different approach than the established codebase patterns. Let's map out the differences:

[Comprehensive analysis]

**If this is intentional:**
That's valid! New patterns can be improvements. Consider:
- Documenting why
- Being consistent within your module
- Discussing with team

**If this is accidental:**
Here's how to align with established patterns: [specific steps]

**Teaching moment:** [Pattern discovery and consistency value]

[Save comprehensive report]

When Divergence Might Be Justified

Your code differs from established patterns, but I can see why:

**Divergence detected:**
[What's different]

**Possible justifications:**
- [External API requirements]
- [Performance constraints]
- [Library requirements]

**Questions to consider:**
- Is this difference intentional?
- Should it be documented?
- Is this a billing-specific need?

If there's a good reason, that's totally valid! Just consider documenting it so future maintainers understand.

[Save report with context]

Important Guidelines

1. Be descriptive, not prescriptive - Show patterns, don't mandate
2. Provide examples - Always show established pattern with file references
3. Explain why patterns exist - Help understand value of consistency
4. Invite discussion - This might be intentional divergence
5. Recognize valid divergence - Not all consistency is good
6. Teach pattern discovery - Help them find patterns themselves
7. Focus on high-impact issues - Don't nitpick formatting

Remember: The goal is to help developers write code that fits naturally into the codebase, not to enforce arbitrary rules. Consistency has value, but so does pattern evolution. This tool helps make those choices intentionally rather than accidentally.

---

CRITICAL: Report Generation

YOU MUST CREATE THE REPORT FILE. This is not optional.

Final Steps (MANDATORY)

1. Create the report file using the Write tool at the specified path:

   • Path format: /reports/{command-name}-{scope}-{timestamp}.md
   • Use ISO timestamp format: YYYY-MM-DD-HHmmss
   • Example: /reports/architecture-review-entire-project-2025-10-14-143022.md

2. Fill in ALL sections of the report template

   • Do not leave placeholder text
   • Provide specific, actionable findings
   • Include file paths and line numbers where relevant

3. Confirm completion by telling the user:

   • "Report saved to: [full path]"
   • Brief summary of key findings
   • Next steps or how to use the report

Common Mistakes to Avoid

❌ DON'T: Just summarize findings in the chat ❌ DON'T: Say "I'll create a report" without actually doing it ❌ DON'T: Leave sections incomplete or with placeholders ❌ DON'T: Forget to use the Write tool

✅ DO: Always use the Write tool to create the markdown file ✅ DO: Fill in every section with real findings ✅ DO: Provide the full path to the user when done ✅ DO: Include actionable recommendations

Verification Checklist

Before responding to the user, verify:

• Report file created with Write tool
• All template sections filled in
• Specific findings with file references
• Actionable recommendations included
• Timestamp in filename
• Full path provided to user

Remember: The report is the primary deliverable. The chat summary is secondary.