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!"