Design docs that are not homework
A generated design document reads like an assignment handed in: complete, fluent, and useless to the phases after it. The mechanism, and the three kinds of document that fix it.
Most design documents are now drafted by a model, and many people have the same uneasy reaction to the result: it reads like a student handing in an assignment. Every section present, the prose fluent, the template honoured, and somehow nothing in it serves the phases that come after. The intuition is correct, and it is worth naming the mechanism, because the fix follows from it.
Two functions, one skipped
A design document has two functions. It is the product of thinking, and it is the process that forces thinking to happen. The model produces the product and skips the process. The reason a design document used to be valuable was never the words. It was that writing it forced the author to choose: weigh options, exclude some, commit. When a model writes it, you receive a fluent text with every heading filled and no decision inside. That is the homework feeling, exactly.
There is a compact test. The value of a document as a record of design is the part that could not be regenerated from the prompt. If you hand a model one sentence of request and get fifteen pages back, those pages may be pleasant to read, the way a good explanation is, but they record no decision: everything in them is derivable from general knowledge plus your sentence. What makes a document valuable is what only you and your situation know. The real constraints: budget, deadline, the level of the team that will maintain it, the infrastructure the customer already runs. The history: we tried X and it failed because of Y. The politics: the customer is afraid of lock-in. The real numbers: current traffic, not “scale to millions”. The model has none of these, so it fills the space with what it does have, which is plausible boilerplate. Plausible is not the same as right for you.
Three signs identify homework when you review a design document. It excludes nothing: a good document says no, not this approach, not that case, while a generated one lists every option with balanced trade-offs and then either does not choose or chooses without any pain. It has no honest non-goals, which is the most valuable section of any design document and the one models write worst, because it requires knowing what you deliberately will not do. And two people who read it would act no differently from two who had not.
Three kinds of document, three treatments
The conclusion is not that people must write everything again by hand. It is to split what used to be one document into three kinds, each treated differently.
Decision documents: decision records, trade-off analyses, constraints, non-goals. The core is held by people, because this is where the non-regenerable information lives. Holding it does not mean typing all of it. The productive process reverses the roles: you write the core as rough bullets, what was decided, why, what was rejected, then let the model be the interrogator rather than the ghostwriter. “Interview me about this design and find what I have not thought about.” “Red-team this decision.” A model draws thinking out of your head far better than it invents thinking on your behalf. Only then let it format and expand. The model writes the sentences, but every claim in the document traces back to a decision you made.
Derived documents: the API reference, diagrams generated from the code, module descriptions, the data dictionary. These can be derived from the codebase; people used to write them by hand, which is why they always drifted. Two kinds sit inside the category and deserve different handling. What a tool extracts deterministically, the API reference from the signatures, the dependency diagram from the imports, the data dictionary from the schema, is build output: regenerated on every build, maintained by nobody. What a model explains in prose, a module description, a summary of a flow, is generated from the code but is still a reading of it, so it is reviewed like any other draft and regenerated when the code it describes changes. Neither is homework, because the source of information, the code, is real. This is also the direct cure for the continuity gap.
Deliverable documents: the ones that exist because a contract or a process requires them. The basic design document and the detailed design document (shousai sekkeisho) of Japanese-style delivery, the compliance evidence pack, the architecture section a procurement questionnaire demands. For these, rendering from the first two kinds is entirely legitimate; it is a rendering problem, not a design problem. The one trap: never let the deliverable replace the decision document internally. Many teams only ever had the third kind and believed they had design documents. That was homework institutionalised before any model existed. The model made it cheap and obvious.
The operating rule compresses to one line: decisions flow down from people, text flows out of the model, and the direction is never reversed. As a review gate for design documents, add three questions to the checklist. What does this document exclude? What does it contain that cannot be derived from the brief? Where are the non-goals? A document that fails all three is homework, whoever wrote it, including whoever had the fewest hours left in the estimate.
It is not only documents
The intuition is right at one more level. The homework mode is not confined to design documents. It is the model’s default for every artifact when the input lacks decisions: homework specifications, homework tests, even homework code that runs, matches the brief, and serves nothing that comes after. Documents are only where you notice it first, because documents exist to be read by a person. The cure is the same everywhere: put the real decisions and constraints in before generating, and measure the output by two questions, does it carry the decisions that went in, and does the phase after it have what it needs.
In Rindo a design page keeps its history, so the decisions in it can be traced to who made them and when, and a review pass by an assistant returns its findings as comments a person reads, with the three questions above as the reviewer’s instructions on the project’s Guidance page.