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