A Better Way to Review Your Design Docs
In a prior post, I wrote about using AI before code—shaping the system in words, building Markdown documents, and reducing drift before implementation starts.
You can read that here: I Don’t Start With Code Anymore
This post is about the next step:
Once you have the documents, ask AI to stop helping and start judging.
If you stripped away all prior context, would your design docs still make sense?
That sounds harsher than it is. But it matters.
By default, AI often tries to be agreeable. It smooths rough edges. It validates your thinking. It finds what is good before it tells you what is weak. That can be useful early on, when you are trying to explore an idea. It is much less useful when you need to know whether your documents actually stand on their own.
At some point, you need the model to stop acting like a collaborator and start acting like a reviewer.
The real test is not whether AI understands you
The real test is whether AI understands your documents without you.
That is a very different standard.
A lot of design work feels coherent inside an ongoing chat because the model is benefiting from your previous explanations, corrections, and intent. It may be using surrounding context to fill in missing assumptions. That can hide weaknesses in the actual documents.
So one of the most useful things I can do is isolate the material.
I start a clean project or fresh conversation with as little extra context as possible. Then I upload only the files that are supposed to define the system: the vocabulary, goals, architecture notes, interfaces, process model, whatever should be sufficient on its own.
Then I ask the model to judge the material based only on that.
That is where things get honest.
Why this works
When the extra context is gone, the documents either carry the meaning or they do not.
If they do, the model can summarize the system, explain the boundaries, identify the phases, and reason about implementation from the files alone.
If they do not, the cracks show quickly:
- terms are undefined
- boundaries are fuzzy
- assumptions are implicit
- phases are inconsistent
- interfaces are under-specified
- important decisions exist only in prior chat history
That is exactly what I want to find.
I would rather discover that weakness while refining the documents than discover it later when a coding agent starts implementing the wrong thing.
Tell the AI to be ruthless
This is the part many people skip.
If you ask AI, “What do you think of these docs?” you will often get a polite answer. It may be thoughtful. It may even be useful. But it will usually soften the critique.
Sometimes that is the wrong mode.
Sometimes you need to tell it, explicitly:
- do not be polite
- do not optimize for encouragement
- do not assume missing details are intentional
- do not fill gaps unless the text supports them
- treat ambiguity as a defect
- treat undefined terms as a defect
- treat hidden assumptions as a defect
- be harsh, direct, and specific
That changes the quality of the feedback.
The goal is not abuse. The goal is objectivity.
You want the model to stop saying, “This is a strong start,” and start saying, “This section fails because it depends on context not present in the document.”
That is far more useful.
What I ask it to evaluate
When I do this, I usually want the model to answer questions like:
- Can you explain this system from these files alone?
- What assumptions are missing?
- Which terms are overloaded, vague, or undefined?
- Where do the documents contradict each other?
- What would an implementation agent still not know?
- Which sections sound precise but are actually ambiguous?
- What depends on prior chat context rather than written material?
That is the audit.
If the model can only understand the system because I already taught it the system in conversation, then the documents are not done yet.
The shift in mindset
This is the big change:
Stop using AI only as a builder. Use it as a hostile reader.
That does not mean every interaction has to be adversarial. Early on, collaboration is useful. Exploration is useful. Drafting is useful.
But once the docs are supposed to be real, you need a different posture.
You need something closer to:
Read this as if you were a new engineer, a coding agent, or a future version of me with no extra context. Then tell me what breaks.
That is where the quality bar rises.
What good feedback looks like
The best feedback is not vague negativity. It is precise pressure.
Good critical feedback sounds like this:
- “This term is used three different ways.”
- “This section implies authority, but never defines the source of truth.”
- “The phase boundary is unclear.”
- “This interface description is incomplete because input shape is missing.”
- “This workflow only makes sense if the reader already knows the unstated constraint.”
That kind of criticism is gold.
It tells you exactly where your design is still living in your head instead of in the docs.
Why this matters before implementation
Once code generation starts, ambiguity gets expensive.
A coding model will happily turn vague documents into concrete code. That is the danger. It has to choose something. If your design artifacts are unclear, the model will still produce output, but that output may reflect assumptions you never intended.
That is why I want brutal feedback first.
I want the documents attacked before I ask for implementation.
If the docs survive that, then they are much more likely to guide coding tools well.
The takeaway
Here is the workflow:
- Build the design documents
- Move them into a clean context with minimal extra history
- Upload only the files that should define the system
- Tell the AI to stop being nice
- Ask it to identify ambiguity, contradiction, and hidden assumptions
- Fix the documents
- Only then move toward implementation
AI is useful when it helps you draft.
It becomes far more useful when it helps you detect where your draft is lying to you.
Not just using AI to help me think.
Using AI to tell me, bluntly, where my thinking is still not good enough.
What’s your approach to getting brutally honest feedback from AI?
Top comments (0)