Initial commit

docs/explanation/tdfddd-manifesto.md

@@ -0,0 +1,90 @@
+# TDFDDD Manifesto
+
+Type-Driven Functional Domain-Driven Design is the design discipline behind this template.
+In casual conversation we call it **Functional Domain Modeling**.
+
+## What the method is trying to achieve
+
+The goal is not to move fast by skipping design.
+The goal is to make the important design decisions explicit enough that implementation becomes mechanical and review becomes reliable.
+
+The core idea is simple:
+
+> Make illegal states unrepresentable.
+
+Instead of writing more and more runtime checks, use types and explicit state shapes so invalid situations are harder to express in the first place.
+
+## The design pressure should come from the workflow
+
+A common mistake is trying to invent the perfect domain model too early.
+That usually produces elegant-looking types that do not actually serve the workflow.
+
+A better heuristic is:
+
+> Let the workflow dictate the state.
+
+Start with the decision the system must make.
+Sketch the policy signature with temporary or incomplete types if needed.
+Once you know what information the workflow needs, model those concepts precisely.
+
+This keeps the design grounded in real use instead of speculation.
+
+## Pure core, impure shell
+
+We separate high-inference design work from mechanical implementation work.
+
+- The **policy** is the pure core. It makes a domain decision from explicit inputs.
+- The **model** applies a state transition using pure data transformations.
+- The **workflow** is the impure shell. It gathers data, calls the policy, applies state changes, persists results, and invokes external capabilities.
+
+This separation is what makes the method reviewable.
+A human can inspect the design in layers instead of trying to reason about everything at once.
+
+## Design before code, but not design as guesswork
+
+You should not jump straight into implementation code.
+But that does not mean you need a perfect domain ontology before you start.
+
+A practical sequence is:
+
+1. Write the story in domain language.
+2. Identify the command and possible events.
+3. Sketch the policy signature.
+4. Invent the minimum types required to make the decision precise.
+5. Freeze the contract.
+6. Translate the design into TypeScript and Effect.
+
+That is why design artifacts matter.
+They preserve the reasoning that a human reviewer is validating.
+
+## Why the human reviewer matters in an LLM-first workflow
+
+In an LLM-first workflow, the model can produce the first draft of the design artifacts.
+The human still has to judge whether the artifacts are sound.
+
+The reviewer is checking questions like these:
+
+- Did the model identify the right command and outcomes?
+- Did it model state transitions instead of hiding them behind status flags?
+- Did it choose types that encode the business constraints?
+- Did it keep policies pure and move orchestration into workflows?
+- Did it return domain facts instead of vague booleans?
+
+The review process only works if the repository preserves examples, templates, and clear standards for comparison.
+
+## What a good finished design feels like
+
+A good TDFDDD design usually has these properties:
+
+- The story can be explained in domain language without mentioning framework details.
+- The command, events, and state variants are easy to name.
+- The policy signature makes the decision boundary obvious.
+- The final implementation looks like translation, not invention.
+- A reviewer can tell what is being verified at each phase.
+
+## Where to go next
+
+- If you want to learn by imitation, start with `../tutorials/worked-example-truck-loading.md`.
+- If you want to practice manually, use `../tutorials/practicing-tdfddd-by-hand.md`.
+- If you want the formal phase breakdown, read `./tdfddd-protocol.md`.
+- If you want to review model output, use `../how-to/review-an-llm-generated-design.md` and `../reference/review-checklist.md`.