feat: add no-premature-simplification rule to steering docs

2026-05-01 04:32:05 +00:00
parent 751cce0509
commit 32535540fe
1 changed files with 11 additions and 0 deletions
@@ -94,6 +94,17 @@ Ingestion jobs MUST include `source_id`, `source_type`, `ticker`, `company_id`,
 - The dashboard Docker build uses TypeScript strict mode — unused imports that pass local diagnostics will fail in CI
 - Ingestion jobs require `source_id` from the `sources` table — don't just pass `ticker`

+## No Premature Simplification
+Do NOT "simplify" code on impulse. When the urge arises to simplify a section, STOP and do this instead:
+
+1. **Evaluate the section**: Read the full function/module, not just the part that looks complex.
+2. **Map the dependencies**: Identify every caller, every consumer, every downstream component that depends on this code's behavior, return shape, or side effects.
+3. **Assess blast radius**: Would changing this function break other implementations? Check imports, tests, API contracts, database queries, and frontend expectations.
+4. **Respect intentional complexity**: If the code is complex because the domain is complex (financial math, multi-layer signal aggregation, Bayesian shrinkage), the complexity is load-bearing. Simplifying it will introduce bugs.
+5. **Only simplify when**: The complexity is accidental (dead code, redundant branches, copy-paste artifacts) AND you have confirmed no downstream dependencies break.
+
+This codebase has interconnected layers (ingestion → extraction → aggregation → recommendation → trading → validation). A "simple" change to a scoring function can cascade through trend summaries, recommendations, snapshot capture, and outcome evaluation. Always trace the full path before refactoring.
+
 ## Documentation
 - Do NOT create large summary/success markdown files after each step
 - Keep notes short, concise, and organized under `docs/notes/`