SpecFlow Positioning Guide
The Core Message
“We already knew how to control untrusted execution. We just forgot — until LLMs forced us to remember.”
The Workflow Comparison (Use Everywhere)
| Most Workflows | SpecFlow |
|---|---|
| Intent → Prompt | Intent → Contract |
| → Hope | → Generate |
| → Review → Fix | → Test → Stop or Ship |
| Trust the middle | Verify the boundary |
The Compiler Analogy (Hero Message)
Headline:
Stop Trusting. Start Verifying.
Subheadline:
SpecFlow enforces architectural contracts like a compiler enforces types.
Call to Action:
The compiler doesn’t trust your types. Why trust your architecture?
The “Why Now” Narrative
Before LLMs (Pre-2023)
- ✅ Execution was deterministic
- ✅ Humans were the bottleneck (slow generation)
- ✅ Review scaled poorly but worked
- ✅ Violations were rare bugs
Old tools were sufficient: DbC, TDD, linters, code review
After LLMs (2023+)
- ⚠️ Generation is infinite
- ⚠️ Execution is probabilistic
- ⚠️ Humans cannot keep up (slow review)
- ⚠️ Drift is invisible until too late
- ⚠️ Violations are normal behavior
Old tools are insufficient. SpecFlow fills the gap.
Intellectual Lineage (5 Closest Patterns)
1. Design by Contract (Eiffel, 1986)
Similarity: Preconditions, postconditions, invariants Critical Difference:
- DbC assumes: Author = executor, violations are bugs
- SpecFlow assumes: Executor is not aligned, violations are normal
In SpecFlow, nothing is trusted by default.
2. Test-Driven Development (TDD, 2003)
Similarity: Write expectations first, tests gate progress Critical Difference:
- TDD: Tests verify correctness
- SpecFlow: Tests enforce containment
Tests aren’t about correctness — they’re about containment.
3. Property-Based Testing (QuickCheck, 2000s)
Closest cousin.
- QuickCheck: Properties for functions
- SpecFlow: Properties for architecture, workflows, systems
SpecFlow is property-based testing for creative systems.
4. Model-Driven Engineering (MDE, 1990s)
Why MDE failed: Too rigid, too heavy, required upfront completeness Why SpecFlow works:
- Model is partial (not complete)
- Enforcement is selective (not total)
- Generation is cheap (minutes, not days)
- Failure is informative (not blocking)
SpecFlow is the lightweight version MDE always wanted to be.
5. Static Analysis (Lint, 1970s)
SpecFlow advantage: Custom rules in YAML (not expert-only)
SpecFlow democratizes static analysis.
The Academic Claim (For Researchers)
What SpecFlow IS claiming:
“A synthesis of compiler and testing theory applied to probabilistic generative systems, where generation cannot be trusted but must be harnessed.”
What SpecFlow is NOT claiming:
- ❌ We invented contracts (Eiffel did)
- ❌ We invented property testing (QuickCheck did)
- ❌ We invented static analysis (Lint did)
What SpecFlow DOES claim:
- ✅ Synthesized patterns for new failure mode (LLM drift)
- ✅ Created journey contracts (temporal specs as DOD)
- ✅ Enabled agent-first generation with automated enforcement
- ✅ Proved DPAO (parallel orchestration with <5% failure rate)
Soundbites (By Page)
| Page | Soundbite |
|---|---|
| Home | “The compiler doesn’t trust your types. Why trust your architecture?” |
| About | “We already knew how to control untrusted execution. We just forgot — until LLMs forced us to remember.” |
| Getting Started | “SpecFlow isn’t testing. It’s containment.” |
| Concepts | “SpecFlow is property-based testing for creative systems.” |
| Background | “SpecFlow isn’t new theory. It’s old theory applied to a new failure mode.” |
The HCI Angle (Often Missed)
SpecFlow mirrors how we treat creative professionals:
Writers, Designers, Composers:
“Write freely. We’ll edit.”
SpecFlow for LLM-generated code:
“Generate freely. Contracts will edit.”
SpecFlow formalizes editing for code generation.
Positioning for Different Audiences
Practitioners (Homepage)
“Stop trusting LLM output. Start verifying boundaries.”
Researchers (Background)
“SpecFlow synthesizes Design by Contract, property-based testing, and compiler theory for probabilistic generative systems.”
Enterprise Architects (Marketing)
“Compilers caught type errors. SpecFlow catches architecture errors.”
Visual: The Shift
Before 2023:
[Human writes code] → [Computer executes]
Bottleneck: Human writing speed
Solution: IDEs, linters, autocomplete
After 2023:
[LLM writes code] → [Human reviews]
Bottleneck: Human review capacity
Solution: Automated contract enforcement
Key Statistics (Use in Marketing)
- 3-4x speedup (Wave 2 Batch 2: 2-3hr vs 4-5 days)
- 11% → <5% failure rate (contract extensions)
- 18 specialized agents (autonomous execution)
- 40+ years of CS foundations (DbC, property testing, static analysis)
Implementation Checklist
- Home page hero uses compiler analogy
- Workflow comparison table on every major page
- “Why Now” narrative in About/Background
- Detailed lineage in Background/Origins
- Academic claim clearly stated
- Soundbites integrated throughout
- HCI angle explained in Concepts
- Statistics prominent on homepage
Priority: CRITICAL
This positioning is the intellectual foundation of the docs site.
Without it: SpecFlow looks like “yet another linter” With it: SpecFlow is “compiler for architecture in the LLM age”
This is the story. Tell it everywhere.