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:

Draft Approach 4 once to validate coherence of the process
Decompose into Approach 1 (PROCESS.md entry point + layered cards)
Audit concept cards: split recipe content into mechanics/, keep theory in concepts/
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.

7.3 KiB Raw Blame History Unescape Escape