Lex Christopherson 9f4bf8c452 fix: restore PR files lost during merge conflict resolution

Files added by PR #2008 that were not in main were dropped during
the merge. Restore all src/, docs/, and scripts/ files from the
pre-merge PR head.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

2026-03-25 22:39:33 -06:00

1.6 KiB

Raw Blame History

Legacy Code & Brownfield Onboarding

The fundamental difference: Greenfield = design → implement. Brownfield = observe → infer → validate → modify.

The Onboarding Pipeline (All 4 Models Agree)

Phase 1: Structural Analysis (Deterministic)

Dependency graph mapping
Module identification, LOC per component
Test coverage analysis, entry point discovery
Database schema mapping

Phase 2: Convention Extraction (LLM-Assisted)

Sample representative files across modules
Identify: error handling patterns, naming conventions, API structure, DB access patterns, testing patterns
Output: a conventions document that becomes critical reference context

Phase 3: Pattern Mining

Extract implicit "tribal knowledge" — workarounds for browser bugs, special customer cases, performance hacks that look like mistakes
Generate decision records into project state

The Cardinal Rules

Rule	Why
Observe first, edit later	Agents must never modify code they don't understand
Preserve local consistency over global ideals	Resist the "Junior Refactor" — don't "fix" legacy code to modern standards
Add characterization tests before modifying	Tests that document current behavior, not correct behavior
Minimal, surgical modifications	Refactoring is a separate task requiring explicit human approval

The Biggest Pitfall

The agent will try to refactor legacy code to match its sense of good patterns. Left unchecked, this produces massive diffs that change behavior in subtle ways. Enforce strict rules: modifications to legacy code should be minimal and surgical.

1.6 KiB Raw Blame History