| name | lisa-protocol |
| description | Lisa Simpson specification-first protocol — 6-phase loop for formal verification, proof-driven development, and evidence-based design |
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!"
