Add additional docs

Signed-off-by: James Ketrenos <james_git@ketrenos.com>

LLM-SHIFT.md

@@ -0,0 +1,63 @@
+# The LLM Shift: From Comprehension Limits to Intention Clarity
+
+## What Fundamentally Changes
+
+**1. Cognitive Load → Verification Load**
+LLMs can hold 100k+ tokens in context and traverse codebases instantly. The bottleneck shifts from "Can I understand this?" to "Can I verify this is correct?" Design now optimizes for **inspectability** and **testability** over raw simplicity.
+
+*New pattern:* Boundaries become verification checkpoints. Each module needs clear invariants and contracts that can be mechanically verified, not just conceptually understood.
+
+**2. Minimize Coupling → Maximize Autonomy**
+When an LLM agent can modify code, loose coupling becomes existential. A poorly bounded module lets the LLM cascade changes across the system. Design for **blast radius containment**.
+
+*New pattern:* Modules become "agentic workspaces" - zones where an LLM can operate freely without risking the broader system. Tests act as guard rails, not just safety nets.
+
+**3. Explicit Dependencies → Explicit Invariants**
+LLMs can trace dependencies easily. What they can't infer are the "why" and the constraints. The critical information shifts from "what depends on what" to "what must never break."
+
+*New pattern:* Property-based tests, design-by-contract, and formal invariants become first-class citizens. Document **constraints**, not structure.
+
+## What Intensifies
+
+**4. Optimize for Deletion → Optimize for Regeneration**
+If an LLM can rewrite a module from specs, deletion is cheap. But so is generation. The new risk: **code obesity** - systems that balloon because generation is easier than curation.
+
+*New pattern:* Design for ephemerality. Distinguish "canonical" (hand-crafted, precious) from "derived" (LLM-generated, disposable). Make derived code obvious and replaceable.
+
+**5. Align with Reality → Align with Intent**
+LLMs amplify misalignment catastrophically. If your domain model doesn't match reality, the LLM will generate mountains of wrong-but-plausible code.
+
+*New pattern:* Invest heavily in **ubiquitous language** and **domain modeling**. The clearer your domain concepts, the better the LLM performs. DDD becomes more important, not less.
+
+## The New Forces
+
+**6. Make the Implicit Explicit**
+Humans rely on context and intuition. LLMs need it spelled out. Tribal knowledge, unwritten rules, "we just don't do that here" - these must be codified.
+
+*New tooling:* Architectural Decision Records (ADRs), explicit design constraints, linting rules that encode team wisdom, comprehensive example-driven documentation.
+
+**7. Design for Observable Correctness**
+When an LLM makes a change, you need to know instantly if it broke something. The faster feedback, the more autonomy you can grant.
+
+*New investment:* Type systems, contract tests, property tests, mutation testing, runtime assertions. Make correctness *visible*, not just possible.
+
+---
+
+## The Principal's New Stance
+
+**You become a curator of constraints, not complexity.**
+
+Your role shifts from "help humans navigate complexity" to "define safe operating boundaries for human-LLM teams."
+
+- **Less time:** Explaining how the system works (LLM does this)
+- **More time:** Defining what the system must never do (LLM needs this)
+
+- **Less time:** Refactoring for readability (LLM reads anything)
+- **More time:** Architecting for verifiability (LLM changes must be checkable)
+
+- **Less time:** Documentation of implementation (LLM can traverse)
+- **More time:** Documentation of intent and constraints (LLM can't infer)
+
+**The paradox:** LLMs make bad design more *tolerable* in the short term (can navigate spaghetti) but more *catastrophic* in the long term (can generate more spaghetti faster than humans can audit).
+
+The answer isn't to abandon design principles - it's to **double down on the ones LLMs can't compensate for**: clear boundaries, explicit invariants, comprehensive verification, and ruthless curation.