# How to Review an LLM-Generated Design This guide is for the human reviewer. Use it when the LLM has produced a design artifact and you need to decide whether it is safe to accept, revise, or reject. ## What you are reviewing You are not primarily reviewing style. You are reviewing whether the design artifact captures the domain correctly enough that implementation will be mostly mechanical. ## Recommended review order ### 1. Read the feature discovery first Start with `design/feature//discovery.md`. Ignore code and framework details at the start. Ask whether the artifact reflects the real business situation, user intent, candidate bounded contexts, and possible outcomes. If the feature story is muddy, everything downstream will be muddy too. ### 2. Check the decomposition map Read `design/feature//design.md`. Confirm that: - bounded contexts are explicit - feature steps map to workflow slices - cross-context handoffs are recorded - the chosen slice actually belongs to one bounded context ### 3. Inspect the slice discovery and core sketch Read `02-discovery.md` and `03-core-sketch.md` for the selected workflow slice. The policy sketch should reveal the decision boundary. It should be obvious what information is needed to make the decision. This is where shallow model output often shows up. If the signature still contains vague blobs like `Data`, `Context`, or `Info`, the design is probably not ready. ### 4. Inspect the F# blueprint Read `04-blueprint.fs`. Look for evidence that the model is encoding business meaning rather than storing everything in generic shapes. Ask: - Are important lifecycle states explicit? - Are primitives replaced with domain concepts where it matters? - Are invalid combinations harder to express? - Is the naming domain-specific and precise? - Is the slice contract frozen clearly enough that assembly is mechanical? ### 5. Inspect separation and boundaries The final contract should separate concerns clearly: - policy for pure decisions - model for pure state transitions - workflow for impure orchestration - feature-level orchestration separate from slice-local decision logic If those concerns blur together, the implementation will likely blur too. ### 6. Compare against the reference example Use these reference docs as comparison material: - `../tutorials/worked-example-truck-loading.md` - `../reference/design-artifact-template.md` - `../reference/review-checklist.md` - `../explanation/naming-for-domain-modeling.md` You are not comparing domain details. You are comparing clarity, shape, and separation of concerns. ## Red flags Common signs that the artifact is not ready: - a generic object with a `status` field where separate states should exist - policy outputs like `true` or `false` with no domain fact payload - workflow concerns mixed into the policy - infrastructure types leaking into the design artifact - naming that sounds like programming jargon instead of domain language - a final contract that still feels invented rather than discovered - a refactor proposal that preserves backwards compatibility without an explicit reason, even though the compatibility requirement keeps a worse design in place ## When to ask the LLM for a revision Ask for a revision when the design fails for reasons of shape, not just polish. For example: - the command or events are wrong - the state model hides important boundaries - the policy does not expose the needed information - the artifact skips from story to code without freezing the design A good revision request is specific. Say what phase is weak and what you want clarified. ## A practical review question A useful test is this: > If I handed this artifact to a careful engineer, could they implement it without inventing missing domain meaning? If the answer is no, the artifact is not ready.