As software engineers, we often need a stakeholder to understand an idea before anyone commits to building it.
We can send a document or walk through user stories in Jira. We know how the screens connect because we already have the product in our heads. The stakeholder hears the same words and has to assemble them into an interface.
They can agree with every user story and leave the conversation picturing a different product.
A clickable prototype removes some of that guesswork. The stakeholder can use the proposed flow while we are still talking. They can point at a screen, question an interaction, and show us where our idea does not match theirs.
We can correct the idea before we turn it into a production plan.
Exploration has a different job
I use prototypes while we decide what to build and refine the idea.
Once we commit to a production system that must serve millions of users, the job changes. We need written requirements, architecture decisions, security constraints, and a plan for scale and operations. That documentation can be a wall of text in Markdown. I am fine with that because the work needs the detail.
The exploration phase has a different problem. We need to find out whether we want the same thing. A stakeholder, designer, and engineer can read one paragraph and form three valid interpretations.
They can inspect one proposed interpretation in a prototype. It does not settle every product decision. The group can see the disagreement while changing the idea still costs little.
Use the prototype to decide what to build. Use documentation to build it for real.
Do your own first review
AI made a thousand-word specification cheap to produce. Reading and verifying those words still costs human attention.
I do not mind AI-generated documentation. I use AI to write and structure documents. The author can direct the model, check every claim, remove weak sections, and send me something they understand.
I want to avoid the other handoff. Someone generates a document, spends less than 30 seconds assessing it, and sends it to me because I make the final call. They saved their time by making me the first-pass filter.
If your name is on the document, read it before you ask me to read it. Decide which parts matter. Check whether the proposal says what you believe.
AI can produce the first pass. You still own the first review.
The same rule applies to prototypes. A generated interface can contain three screens nobody asked for and a flow that ignores the stakeholder’s main constraint. We get faster feedback from a clickable artifact after someone has checked that it represents a serious proposal.
Let the question choose the artifact
During exploration, I want an artifact that exposes the part we need to discuss.
- UI and UX: a clickable prototype. The stakeholder can see the hierarchy, follow the flow, and react to the interaction while we are talking.
- Business logic: a runnable script or state driver. We can perform the actions, watch the state change, and find the transition that sounded fine in prose but fails in use.
- Intent and constraints: clean Markdown. We should write the goal, trade-offs, and reasons behind a decision because a prototype cannot preserve the full reason we chose it.
I also prefer clean Markdown as the source for knowledge that people and LLMs will need later. We can generate HTML or use MDX when a richer human view helps. I do not want styling and rendering noise inside an architecture description with no interactive purpose.
Three versions before one decision
I use the Prototype skill from Matt Pocock’s package for UI exploration. It creates three variants with different structures on the same route. I can switch between them and compare real options instead of accepting the model’s first answer.
I often do not choose one complete variant. I take the header from A, the information hierarchy from B, and an interaction from C. Comparing them helps me describe the version I wanted but could not express in the first prompt.
The three variants can still repeat one assumption. If all of them use a card grid, the model gave me one design with small changes. I can reject that pattern and ask for a different structure.
I use the same loop with a stakeholder and when I work alone with an LLM. Editing paragraphs about an imagined interface creates slow feedback. Clicking through several interpretations lets me point to what should stay, move, or disappear.
Use the prototype, then write the system
We use the prototype to decide what we want to build. Then we design the production system.
After the exploration, we capture the decisions and start the engineering work. We write the requirements and architecture detail. We address scale, security, integrations, maintenance, and the parts a disposable prototype did not need to solve.
We choose a new planning medium when we start answering production questions.
During exploration, I need the stakeholder to understand and challenge the proposed experience. During production design, I need the team to build a system that survives reality. We use a clickable prototype for the first conversation and detailed Markdown for the second.
The next time you need a stakeholder to back an idea, give them enough prose to understand the problem and a prototype they can challenge. Let them point to what feels wrong while you are there, before the team writes Jira stories around an interpretation nobody agreed on.