dotfiles/claude/memory/feedback-scss-file-organization-not-kitchen-sink.md

permalink

permalink
claude-memory/feedback-scss-file-organization-not-kitchen-sink

---

name: SCSS file organization — don't kitchen-sink into the most recently-touched file description: Steward caught 2026-04-28 evening — across the day's apparatus work I added .preface, .section-break, .sequence-marker, and was about to add .sequence-index-* styles all to _sidenotes.scss because that's the file I had been editing. The file's own header declared its scope as §XII + §XII.b. I was violating that declared scope by aggregation. Steward verbatim: "why in sidenotes.scss?" type: feedback originSessionId: e5a1fa7c-cae6-49c4-8678-e27ce379639b

Pattern caught: when adding new CSS rules in a focused work session, I default to dropping them in the most recently-touched SCSS file (proximity bias) rather than the file scoped to their concern. Across one day's evening work I added four unrelated apparatus blocks (preface, section-break, sequence-marker, sequence-index) all to _sidenotes.scss — whose own header comment declared its scope as §XII Sidenotes + §XII.b Register Markers.

Steward correction (verbatim): "why in sidenotes.scss?"

Why this matters

• The file's declared scope IS the contract. Adding orthogonal concerns silently turns a focused partial into a kitchen-sink. Future readers (including future me) lose the file's organizing principle.
• Cousin to blame-the-exotic-before-checking-the-boring (saved 2026-04-28 earlier today): same shape — defaulting to the path of least resistance instead of the principled one. Different domain (file org vs diagnostics), same root impulse.
• DX cost compounds: a partial named _sidenotes.scss becomes harder to grep, refactor, or hand off to a collaborator when it secretly contains preface/section-break/sequence/etc.

How to apply

• Before adding a new SCSS rule, check the target partial's header comment / declared scope. If the rule belongs to a different concern, create a new partial OR find the right existing one.
• One concern per partial is the working norm in scss/AldineXXI/. The split is by spec section (§XII Sidenotes), apparatus type (preface, section-break), or page-type (sequence-index, post, layout).
• @import order in main.scss is already sectioned with comments (// 7. Sidenotes (§XII)…, // 7.b Preface (§XII.c)…). Honor that organization — add new imports in the right numbered slot.
• If a partial has been growing across concerns, surface it for refactor before adding the next rule. The cost of pausing to split is much smaller than the cost of a kitchen-sink that compounds.

Refactor as recovery

When caught (as today), the recovery is:

1. Identify the partial's true scope (re-read its header comment).
2. Split the orthogonal concerns into properly-scoped new partials.
3. Update main.scss imports with section comments preserving the spec mapping.
4. The file returns to its declared shape; new partials inherit the discipline.

Today's recovery: split _sidenotes.scss into _preface.scss, _section-break.scss, _sequence.scss — each with a proper header comment naming its concern. Imports added to main.scss at slots 7.b, 7.c, 7.d (preserving the §XII numbering visually).

Cross-references

• Cousin: feedback-blame-the-exotic-before-checking-the-boring (2026-04-28) — same proximity-bias / path-of-least-resistance shape, different domain.
• Cousin: feedback-canonical-workstream-tracker-discipline (2026-04-26) — also a file-organization discipline (canonical trackers, not parallel siblings).
• Sibling: the would-Alexander-do-it? test (2026-04-27) — one pattern at a time; bulk-scaffold instinct fights principled placement.