SecondBrain/2026-03-13-oo-principles-plugin-concept-design-recommendations.md

---
source: "hyperthrive_dev"
date: "2026-03-13"
tags: [plan, plugin, oo-principles, ai-conventions, rails, process-driven, refactoring, conventions-architecture]
---

# OO Principles Plugin Concept — Design Recommendations

Gap analysis of the current OO principles conventions structure and architectural recommendations for evolving it into a standalone plugin. Based on a session combining study of 99 Bottles of OOP with external research on AI coding conventions practices.

The intent is to build the plugin separately and validate it in a new project before applying to this workspace. Primary tools: this workspace's conventions setup as the baseline, and the NotebookLM notebook at https://notebooklm.google.com/notebook/7e69f896-972e-4f5d-ad2c-152259efa62a

## Current State Assessment

The existing `conventions/oo-principles/` structure is **accurate but inert**. It captures individual principles correctly (TDD, Shameless Green, Flocking Rules, SRP, LoD, DI, etc.) but provides no decision-tree guidance for when to apply them. An AI agent reading these docs understands *what* each principle is, but not *when to use it*, *in what order*, or *how to transition between development phases*.

**Structural inventory:**
- `QUICK_REFERENCE.md` — one-pager overview, lean and token-efficient
- `cards/` — individual principle cards (~25 lines each), accurate and focused
- `bundles/` — role-based concept bundles (developer, dev-lead, architect)

**What the AI loses without process guidance:**
- No criteria for Flocking Rules vs. Replace Conditional with Polymorphism
- "Refactor later" (Shameless Green) is undefined — when is "later"?
- No principle prioritization when multiple smells coexist
- The 4-phase development lifecycle doesn't exist anywhere in the codebase

## The Gap: Concrete Examples

**Example 1 — Flocking vs. Polymorphism:** An AI sees a `case` statement. The docs say it violates Open/Closed but don't say: "Use Flocking Rules for 2–3 cases; use Replace Conditional with Polymorphism when cases will grow beyond 3 or when a new requirement adds another branch."

**Example 2 — When to refactor:** Shameless Green says "tolerate duplication, refactor later." No definition of "later." Should the AI refactor after the next test? After the next requirement? Only when a requirement forces it?

**Example 3 — Which smell first:** Multiple smells coexist (SRP + LoD + DI). No prioritization order. The correct order is: DI first (is the dependency injected?), then LoD (are we chaining?), then SRP (is this class doing too much?).

**Example 4 — Phase detection:** An AI getting a new requirement can't tell if it's in Phase 1 (keep building Shameless Green) or Phase 3 (stop, check if code is open, refactor before implementing).

## Recommended Architecture: Two-Layer Hybrid

Based on external research (Codified Context paper) and brainstorming, the recommended structure is:

**Layer 1 — Process/Routing Layer** (~400–600 tokens, loaded at role-bundle level):
- `PROCESS.md` encoding the 4-phase lifecycle as decision gates
- Phase entry conditions ("This applies when...")
- Key branch points: "Is the code open?", "Which smell to fix first?", "When to use Flocking vs. Polymorphism?"
- An escape hatch: "If no phase fits, document your reasoning"
- References Layer 2 but does not include it

**Layer 2 — Mechanic Layer** (on-demand, 400–800 tokens per file):
- One file per executable recipe: flocking-rules-recipe.md, replace-conditional-recipe.md, factory-recipe.md, extract-class-recipe.md, etc.
- Self-contained, readable in isolation
- Includes worked examples (one canonical example > three paragraphs of description)
- Separate from theory — concept cards remain as Layer 3 "why" depth

**Layer 3 — Theory Layer** (rarely loaded):
- Existing concept cards, retained as-is or lightly reorganized
- Loaded when AI needs to understand the rationale

## On Opportunistic Refactoring (Phase 2)

The book's conservative "wait for a requirement" stance was written for human teams where refactoring has real cost. AI changes the calculus: the mechanical recipes are exactly the kind of structured, low-ambiguity work AI excels at. The cost of refactoring itself approaches zero.

**The risk that remains:** Premature *abstraction* (not smell-fixing) still locks in wrong designs. Three similar lines of code is safer than a premature abstraction that guesses wrong.

**Recommended Phase 2 scope for AI:**
- Law of Demeter violations (chained message sends)
- Hard-coded class names
- Push object creation to edges / dependency injection improvements
- **Gate:** Only when tests are fully green AND the diff is reviewable as a single coherent unit
- Do NOT leave "fix code smells" open-ended — AI will interpret it too broadly

## Four Architectural Approaches (Brainstorm)

Ranked from least to most disruptive:

**Approach 1: Process-First Entry Point** (recommended first move)
Add `PROCESS.md` as new primary entry point. Existing concept cards remain, linked from the process doc. Minimal restructuring, additive change. Risk: if PROCESS.md is poorly written, the AI is misled — single point of failure.

**Approach 2: Situational Trigger Files**
`situations/when-requirement-arrives.md`, `situations/when-code-is-not-open.md`, etc. Very low per-file token cost; AI narrates which decision node it's at. Risk: AI must correctly self-diagnose situation; link chains can go stale.

**Approach 3: Phase-Bundled Context Packs**
One self-contained file per phase. Clean narrative, maps to how teams talk about work. Risk: content duplication across phases; Phase 3 complexity is hard to flatten; phase misidentification is a failure mode.

**Approach 4: Annotated Process Graph** (good as drafting exercise only)
Single PROCESS.md with everything inline. Zero navigation overhead. Risk: 1500–2500 tokens paid upfront on every load; single document is hard to update surgically; resists progressive disclosure.

**Recommended sequence:**
1. Draft Approach 4 once to validate coherence of the process
2. Decompose into Approach 1 (PROCESS.md entry point + layered cards)
3. Audit concept cards: split recipe content into `mechanics/`, keep theory in `concepts/`
4. Add explicit Phase 2 gates

## Plugin Design Notes

When building as a standalone plugin (not modifying this workspace):
- Model the plugin on the three-tier architecture: constitution (routing) + specialist agents (mechanic recipes + role bundles) + knowledge base (theory cards)
- The plugin's entry point should be role-aware: a developer loads differently than an architect
- Include the 4-phase process as a loadable context pack, not as always-loaded content
- The NotebookLM notebook can serve as the knowledge base layer for deep reference during plugin development
- Validate on a new project first before applying to this workspace

## Current Workspace Observation

This workspace already has the correct three-tier architecture: `CLAUDE.md` → `.CLAUDE.md` files → concept cards. The architecture is sound. The gap is content format (concept lists instead of mechanic recipes with worked examples) and missing process routing layer.

## See Also

- [[99 Bottles OOP — Full Software Design Process Map]] — the lifecycle being encoded
- [[AI Coding Conventions Organization — External Research Synthesis]] — external practitioner patterns this plugin should incorporate