The Agent Solution Designer: Dreaming in Markdown

The Blank Page Problem

One of the most paralyzing moments in software development is the "Blank Page." You have an idea—maybe "I want a dashboard for F1 race data"—but the gap between that sentence and a working React application is an abyss of a thousand decisions.

Which database? Postgres or DuckDB?

Which frontend framework? Next.js or raw HTML?

How do we handle auth?

What does the data schema look like?

If you ask a standard Coding Agent these questions, it will usually pick the path of least resistance. It will suggest whatever tutorial it saw most frequently in its training data (probably a To-Do list app pattern) and try to shoehorn your complex race strategy tool into it.

The result is "Tutorial-Ware": code that looks correct on the surface but collapses under the weight of actual business requirements.

This is why we created The Agent Solution Designer.

The Role of the Visionary

The Solution Designer is the first link in our agentic chain. Its system prompt explicitly forbids it from writing code. Its output is not a .py file; it is a vision.

We realized that LLMs are actually fantastic at synthesis. If you feed them vague requirements, they can halluncinate diverse architectural options. The problem arises when they try to implement those options immediately. They skip the critique phase.

So, we separated the "Dreaming" from the "Doing."

The Solution Designer’s job is to:

1. Interrogate the Human: "You said you want a dashboard. Who is it for? Do you need real-time data? Is this for mobile or desktop?"

2. Explore the Trade-space: "We could build this as a CLI tool, a TUI (Terminal UI), or a Web App. Here are the pros and cons of each."

3. Define the "North Star": Create a High-Level Design (HLD) document that serves as the blueprint for the rest of the project.

The Design Artifacts

When the Solution Designer finishes its work, we don't just have a chat log. We have concrete markdown artifacts that live in the repo before a single line of code exists.

1. The intent.md

This is the "Why." It captures the user's raw request and refines it into a problem statement. It prevents the project from drifting into "cool tech looking for a use case."

2. The architecture_decisions.md (ADR)

This is crucial. The Solution Designer essentially argues with itself.

* Option A: Use SQLite. Fast, simple, local.

* Option B: Use Postgres. Scalable, complex, requires Docker.

* Decision: We choose SQLite because the "Prime Directive" values simplicity and the dataset is <1GB.

By forcing the agent to write down why it chose SQLite, we prevent the Coding Agent from randomly switching to Postgres three days later because it "felt like it."

3. The domain_model.md

Before we talk about database tables, we talk about concepts. "A Race has many Drivers. A Driver has many LapTimes." This conceptual modeling is where LLMs shine. They can derive complex relationships from simple descriptions, effectively doing the job of a Senior Data Architect in seconds.

## Handoff: The "Throw it Over the Wall" Moment

The most critical part of the Solution Designer's job is knowing when to stop.

In our system, once the HLD is approved by the user, the Solution Designer’s permissions are revoked. They cannot change the spec. They cannot "help" the coder. They are done.

They package up the markdown files and "throw them over the wall" to the Business Analyst Agent.

This separation is vital. It stops the "Feature Creep." If I want to add a feature later, I can't just tell the coder to "hack it in." I have to go back to the Solution Designer, update the vision, and have it flow down the waterfall.

Lessons Learned

Using an Agent Solution Designer taught us that Ambiguity is the enemy of Determinism.

Most coding failures aren't syntax errors; they are ambiguity errors. The Coder didn't know if the date format should be YYYY-MM-DD or DD-MM-YYYY, so it guessed. And it guessed wrong.

The Solution Designer’s sole purpose is to hunt down ambiguity and kill it with documentation. It forces us, the human users, to articulate what we actually want. It acts as a mirror, reflecting our vague requests back to us as concrete plans.

And often, looking at that plan, we realize: "Actually, that's not what I wanted at all."

And that is the victory. Creating a markdown file costs $0.05. Writing the wrong code and debugging it for a week costs... well, your sanity. The Agent Solution Designer saves us from ourselves, one markdown file at a time.