Clarity Bear: From idea to specificationAn interview app for thinking through a software idea.
Building Idyllic - Prior Iterations
October 2024
I tried using an AI interview to turn a braindump into a specification. I wrote down a rough idea, had AI process the context, then answered questions about it. The result was a list of action items in a useful order and at a level of detail I could work with. I wanted to make that process into an Idyllic app.
We called it Clarity Bear. Its job was to help a person develop an incomplete idea far enough to produce an editable specification. The application needed to retain the original intention, learn from the answers and choose questions that filled meaningful gaps. A conversation could continue indefinitely without doing any of those things particularly well.
Giving the interview a beginning and an end
I drew four pages: braindump, processing, interview and review. The braindump page gave the person a document editor in which to write freely. Processing would turn that material into an outline and prepare the interview. The interview would gather missing details, and review would display the specification produced from them.
For the first implementation, I planned to hardcode these pages and their server routes. The design below describes that planned application. Working through a particular interview would give me a better account of what a general builder needed to express than starting with a catalogue of hypothetical interview features.
Choosing a question from what is still missing
Each run of the app would have its own conversation. After an answer, an agent process would examine the conversation history, update a scratchpad and choose another question. The scratchpad was intended to organize what the interview had learned against a rubric, including matters such as success criteria and next steps.
An illustrative walkthrough makes the intended behavior easier to see. Suppose the initial braindump says, “I want to build a journal app.” An early question could establish what the person wants the journal to help them do. If the answer is that they want to recover useful ideas from earlier entries, the interview has learned something that should change the remaining questions. It now has a reason to ask how those ideas would be found and used.
The answer also belongs in the developing specification. Asking a good follow-up would be of little help if the final document reverted to a generic journal app. The scratchpad and conversation history gave the generation step material from both the original braindump and the clarifications that followed it.
The next question should come from an unresolved part of that account. If the person has already explained the desired result, asking for the goal again wastes the answer they gave. If they have described a large system but no first useful step, a question about the smallest next step can make the specification more actionable. The rubric was meant to give the loop this direction, so that each answer changed what the app needed to learn next.
This made the interview a stateful program. The latest message was an input to an operation that also read earlier information, revised a working account and selected an action. The visible question was one output of that operation. Progress toward the review screen was another.
Letting the person decide when to review
I proposed a clarity score to indicate when the interview had gathered enough information. Once the score crossed a threshold, the interface would offer a way to finish and generate the specification. Crossing that threshold would make the exit available; the person would choose whether to take it.
The score's meaning still needed to be worked out. We had no calibration establishing that a percentage could reliably measure the completeness of a project specification. Its role in the design was to connect the interview's internal assessment with a visible control.
A related Figma design shows that relationship. The conversation sits beside a clarity meter and a “Show results” control. The example percentage gives the indicator a visual form, while the button gives the person a concrete next action.
That distinction mattered because “enough information” depends on the intended use of the result. A person might want a first draft of the specification while some decisions remain open. The interface could offer review without treating the agent's assessment as an order to end the conversation.
Carrying the answers into an editable specification
The information-flow sketch brings the inputs together. The braindump contributes the initial idea and outline. The interview contributes questions, answers and the scratchpad. The final generation step uses those materials to create a task list.
I wanted the result to use editable document blocks, with tasks that could connect to Linear. The specification needed to remain useful once the interview stopped. If it contained a mistaken assumption, the person should be able to correct that part of the document. If a task needed revision, they should be able to work on the task itself.
This connected Clarity Bear to a broader problem I was encountering in AI interfaces. A useful result could become difficult to work with when it existed only as text inside a past message. Giving an artifact an identity and an editor would let later operations refer to the same result and change it deliberately.
For Clarity Bear, the concrete requirement was a document assembled from the whole interview and available for further editing. The app builder would also need to describe how an answer changed the scratchpad, how that changed the next question, and when a control could take the person to review. Those connections were the next part of the application I needed to represent.