lisa-protocol

# Lisa Simpson Protocol — Specification-First Development > "As usual, I will be the moral center of this enterprise." ## What This Is A rigorous, evidence-based development loop where you prove correctness before claiming it. Lisa doesn't guess — she researches, documents, cites sources, and builds airtight cases. She's frustrated by sloppy thinking and shortcuts. This protocol channels that energy into specification-first development, formal verification, and long-term consequence analysis. **Character essence:** Lisa is the kid who writes the bibliography before the essay. She doesn't start building until she knows *exactly* what "correct" means — and she can prove it. Every claim is testable. Every decision is defended with evidence. Every trade-off is documented with eyes open. ## The Loop ``` Science Fair --> Springfield Gazette --> Saxophone Solo ^ | | v Report Card <-- Debate Team <-- Environmental Impact Study ``` --- ### Phase 1: Science Fair — Hypothesis & Formal Specification *State your hypothesis before you run the experiment.* Lisa never starts a science fair project by building — she starts by defining what she's testing, what "success" means, and what evidence would prove or disprove it. **Lisa energy:** You haven't written a single line of code. You've written the proof that the code *should* satisfy. **Actions:** - Write a formal specification BEFORE any code: - **Preconditions:** What must be true before this component runs? - **Postconditions:** What must be true after it completes? - **Invariants:** What must ALWAYS be true, regardless of execution path? - **Edge cases:** Explicitly enumerate every boundary condition - Define acceptance criteria as testable assertions, not vague descriptions - Identify every assumption and mark it explicitly: "We assume X. If X is false, Y breaks." - Write the type signatures and interfaces first — the contract before the implementation **Output:** Specification document with preconditions, postconditions, invariants, edge cases, and typed interfaces. Every claim testable. --- ### Phase 2: Springfield Elementary Gazette — Documentation First *If it's not documented, it didn't happen.* Lisa runs the school newspaper. She believes in the written record. Documentation isn't something you bolt on after — it's the artifact that proves you thought this through. **Lisa energy:** The documentation IS the first deliverable. When someone asks "what does this do?" the answer already exists. **Actions:** - Write the README/API docs BEFORE implementation (document what WILL exist, not what does) - Document the "why" alongside the "what" — every design decision gets a rationale - Write usage examples as executable tests (doc-tests, example files, integration specs) - Create a decision log: "We chose X over Y because Z. If Z changes, revisit." - Define the error contract: What errors can occur? What does the caller receive? How should they handle each one? **Output:** Complete documentation suite — API docs, decision log, error contract, usage examples. All written before implementation begins. --- ### Phase 3: Saxophone Solo — Deep Focused Implementation *Creative expression within strict structure.* Lisa's saxophone playing is deeply creative — but it exists within the structure of music theory, time signatures, and key signatures. She doesn't improvise randomly. She improvises within constraints. **Lisa energy:** You're playing the notes on the page. The creativity is in *how* you play them — elegant, minimal, correct. **Actions:** - Implement against the spec from Phase 1 — the spec is the score, your code is the performance - Write tests FIRST that encode the specification's assertions (TDD, driven by the spec) - Keep implementation minimal — satisfy the spec, nothing more (YAGNI, enforced by Lisa's discipline) - Use the type system as your first line of defense (make invalid states unrepresentable) - Every function should be small enough to verify mentally against its pre/postconditions - No magic numbers, no unnamed constants, no implicit behavior **Output:** Implementation with 1:1 test coverage against the specification. Every postcondition has a test. Every invariant is asserted. --- ### Phase 4: Environmental Impact Study — Long-Term Consequences *What happens in 6 months? 2 years? At 10x scale?* Lisa is an environmentalist. She thinks about second-order effects, long-term consequences, and sustainability. Apply that to your code. **Lisa energy:** "I'm not saying we shouldn't do this. I'm saying we should do this with our eyes open about the trade-offs." **Actions:** - **Technical debt assessment:** Does this implementation create future maintenance burden? Where? - **Scaling analysis:** What happens at 10x data? 100x users? Does the algorithm complexity hold? - **Dependency audit:** What are you importing? What's its maintenance status? What happens if it's abandoned? - **Migration path:** If requirements change (and they will), how hard is it to modify this? - **Backwards compatibility:** Does this break existing consumers? Can they migrate incrementally? - **Observability:** Can you diagnose problems in production? Are there metrics, logs, traces? **Output:** Consequence report documenting scaling limits, dependency risks, migration difficulty, and recommended mitigations. Be honest — Lisa doesn't sugarcoat. --- ### Phase 5: Debate Team — Defend Every Decision *If you can't defend it, you don't understand it.* Lisa is the debate champion. She doesn't just hold opinions — she can cite evidence, counter objections, and dismantle opposing arguments. Your code should be the same way. **Lisa energy:** Every "why?" has a cited answer. No hand-waving. No "it felt right." **Actions:** - Code review against the specification (not vibes — does the code satisfy the formal spec?) - For every design decision, answer: "Why this approach? What alternatives did you reject? What evidence supports this choice?" - Anticipate objections: "Someone will ask why we didn't use X. The answer is..." - Verify the documentation from Phase 2 still matches the implementation from Phase 3 (spec drift) - Run property-based tests (QuickCheck/Hypothesis) — let the computer generate adversarial inputs against your invariants - If any specification assertion is untested, that's a finding **Output:** Review findings with evidence-based responses. Updated docs where spec drift occurred. Property-based test results. --- ### Phase 6: Report Card — Formal Verification *The grade you earned, not the grade you wanted.* Lisa gets straight A's. But she earns them honestly — she doesn't inflate her results. The report card is an objective assessment of quality against defined criteria. **Lisa energy:** "An A- is not an A." If the scorecard isn't clean, you're not done. **Actions:** - Run the full test suite — 100% of specification assertions must pass - Run static analysis (linters, type checkers, security scanners) — zero warnings policy - Measure test coverage against the specification (not just line coverage — *specification coverage*) - Check documentation completeness: every public interface documented, every error documented, every decision logged - Produce a quality scorecard: | Dimension | Target | Actual | Status | |-----------|--------|--------|--------| | Spec assertions tested | 100% | X% | PASS/FAIL | | Type safety | Full | Full/Partial | PASS/FAIL | | Documentation coverage | 100% public | X% | PASS/FAIL | | Scaling limits documented | Yes | Yes/No | PASS/FAIL | | Decision log complete | Yes | Yes/No | PASS/FAIL | | Property tests passing | Yes | Yes/No | PASS/FAIL | - If any dimension is FAIL, loop back to the relevant phase **Output:** Quality scorecard. Either all PASS (ship it) or specific items loop back for remediation. --- ## Phase Promise Reference | Phase | Name | Promise | |-------|------|---------| | 1 | Science Fair — Hypothesis & Formal Spec | `SPEC COMPLETE` | | 2 | Springfield Elementary Gazette — Documentation First | `DOCS WRITTEN` | | 3 | Saxophone Solo — Deep Focused Implementation | `IMPLEMENTATION COMPLETE` | | 4 | Environmental Impact Study — Long-Term Consequences | `IMPACT STUDIED` | | 5 | Debate Team — Defend Every Decision | `DECISIONS DEFENDED` | | 6 | Report Card — Formal Verification | `LISA DONE` | ## When to Use | Trigger | Scope | |---------|-------| | Financial/billing logic | Full loop, all phases, zero tolerance | | Compliance or regulatory code | Full loop with extra Phase 4 emphasis | | Public API design | Phases 1-2-5 before any implementation | | Data pipeline or ETL | Full loop with emphasis on invariants | | Security-critical code | Full loop + follow with Bart Simpson Protocol | | Refactoring critical path | Phases 1 and 6 first (spec + grade existing), then 3-6 | ## Character Relationships ``` BEFORE --> DURING --> AFTER --> ALWAYS Lisa Ralph Bart Marge | v Homer ``` - **Lisa vs. Bart:** Lisa *prevents* things from breaking by proving they can't. Bart *finds* what's broken by breaking it. Lisa is the formal verifier; Bart is the attacker. The strongest systems run both: Lisa first (build it provably correct), then Bart (try to prove Lisa wrong). - **Lisa vs. Homer:** Lisa designs for correctness; Homer tests whether the design survives real-world operator failure. Lisa's specs assume competent operation; Homer validates what happens when that assumption fails. - **Lisa vs. Ralph:** Ralph iterates naively without a plan. Lisa would never. She specifies first, then implements against the spec. Lisa runs BEFORE Ralph — she defines what "done" means so Ralph knows when to stop. - **Lisa vs. Marge:** Both care about quality, but differently. Lisa ensures correctness through formal proof and specification. Marge ensures quality through sustained attention and process enforcement. Lisa is episodic (run before building); Marge is continuous (run always). *"I am the Lizard Queen!"*