brownfield-integration

What this skill does

# Brownfield Integration

## Overview

Guidance for implementing tasks that touch existing code. When a task says `[EXTEND]`, add new code following existing patterns. When a task says `[MODIFY]`, change specific behavior as described. In both cases, read the existing code first and respect what is already there.

**The existing code is not wrong until proven otherwise.** It has consumers, tests, and patterns that evolved for reasons not immediately visible.

**Violating the letter of the rules is violating the spirit of the rules.**

## When to Use

- Tasks marked with `[EXTEND]` — adding new functionality to existing files
- Tasks marked with `[MODIFY]` — changing existing behavior in files
- Any task that references files already on disk
- When following patterns established by previous cycles

## When NOT to Use

- Greenfield tasks creating entirely new files
- Tasks with no reference to existing code
- Refactoring work (which should not happen during cycle execution)

## Core Process

### EXTEND vs. MODIFY Semantics

| Marker | Meaning | Scope | Interface Impact |
|--------|---------|-------|-----------------|
| `[EXTEND]` | Add new code alongside existing code | New functions, new methods, new exports | MUST NOT change existing function signatures, exports, or type contracts |
| `[MODIFY]` | Change existing behavior | Specified sections only | MAY change function internals; MUST NOT change signatures unless task explicitly says so |

**Never MODIFY when the task says EXTEND.** If you believe the existing code cannot support the extension, flag it in the cycle report — do not silently rewrite.

### Read-Before-Write Checklist

Before writing any code in an existing file, complete all five steps:

1. **Read the full file** — not just the section you plan to change. Understand the complete context.
2. **Identify naming conventions** — variable naming (camelCase, snake_case), file naming, function naming patterns. Follow them exactly.
3. **Identify error handling patterns** — how does existing code handle errors? Try-catch, Result types, error callbacks? Match the pattern.
4. **Identify import style** — relative vs. absolute imports, named vs. default exports, import ordering. Follow the same style.
5. **Identify test patterns** — if the file has tests, how are they structured? Match describe/it nesting, assertion style, fixture patterns.

### Interface Preservation

When extending existing code:

- Do NOT change function signatures (parameter order, types, return types)
- Do NOT change export surfaces (what is exported, export names)
- Do NOT rename existing variables, functions, or classes
- Do NOT change the file's public API unless the task explicitly says `[MODIFY]`
- DO add new exports alongside existing ones
- DO follow the file's established patterns for new code

### Conflict Detection

Before adding new code, check for:

- **Name collisions** — search the file for the function/class/variable name you plan to add
- **Import collisions** — verify your new imports don't shadow existing ones
- **Test file alignment** — if adding to `user.ts`, check that `user.test.ts` exists and follow its patterns
- **Circular dependencies** — verify your new imports don't create circular reference chains

### When to Flag

Flag in the cycle report (do NOT silently resolve) when:

- Existing code contradicts the task description
- The file's patterns are inconsistent (multiple conflicting conventions)
- The task says `[EXTEND]` but the existing interface cannot support the addition without modification
- Existing tests would break from the addition (interface leak)
- The file has no tests but the task expects test-first development

## Common Mistakes

### Mistake: Not Reading the Full File

**What goes wrong:** You add code that duplicates existing functionality, uses different naming conventions, or conflicts with code you didn't see.

**Fix:** Always read the entire file before making any changes. Skim is not sufficient for brownfield work.

### Mistake: Silently Rewriting When Asked to Extend

**What goes wrong:** Existing consumers break because the interface changed. Tests fail for unrelated code. The cycle report doesn't explain why unrelated files were modified.

**Fix:** EXTEND means extend. If you cannot extend, flag it. Never silently rewrite.

### Mistake: Ignoring Existing Error Handling

**What goes wrong:** Your new code throws raw exceptions while the rest of the file uses Result types. Or your code returns null while existing code throws. Inconsistency confuses consumers.

**Fix:** Step 3 of the Read-Before-Write Checklist. Match the existing error handling pattern exactly.

### Mistake: Adding "Better" Patterns

**What goes wrong:** You introduce a "better" pattern alongside the existing one. Now the file has two patterns. The next developer doesn't know which to follow. Consistency is more valuable than local improvement.

**Fix:** Follow existing patterns, even if you'd prefer different ones. Note the improvement opportunity in the cycle report.

## Common Rationalizations

| Excuse | Reality |
|--------|---------|
| "This file is small, I can just skim it" | Small files have hidden conventions. Read the full file. Step 1 exists because skimming misses patterns. |
| "My pattern is better than what exists" | Consistency is more valuable than local improvement. Two patterns in one file is worse than one imperfect pattern. |
| "The existing code doesn't follow best practices" | Existing code has consumers. Introducing a second convention creates confusion. Note it, follow it. |
| "I need to refactor to make my extension work" | If EXTEND doesn't fit, flag it. Silent refactoring breaks existing consumers. |
| "The interface is obviously wrong" | It made sense to someone with context not visible now. Read more before judging. |
| "I'll just fix this one small thing while I'm here" | Scope creep starts with "just one thing." Note it in the report, don't act on it. |

## Red Flags — STOP and Reconsider

- "This existing code is messy, I'll clean it up" — Not the current scope. Note it, don't fix it.
- "I'll use a better pattern here" — Consistency beats local optimization. Follow what exists.
- "The existing tests don't cover this" — That's a pre-existing gap, not a problem to fix now.
- "I need to refactor this to make my change work" — Flag it in the cycle report. Don't silently refactor.
- "This interface doesn't make sense" — It made sense to someone. Read more context before judging.

**No exceptions:**
- Not for "obviously broken" code
- Not for "trivially better" patterns
- Not for "quick cleanup while I'm here"
- Not even if the existing code has no tests
- Not even if the existing naming is inconsistent