If the PRD.md is the soul of a project, the JOURNEYS.md is its nervous system. As someone who spent years as a UX Lead before moving into broader product leadership, I have a deep-seated belief that user flow is everything. A feature is useless if the friction to reach it is too high. When building with AI agents like Cursor, this file becomes the bridge between a high-level concept and the actual clicks, hover states, and transitions that define a user’s experience.
The process of writing this file is where the “tinkerer” energy really hits its stride. It is not about writing a dry technical specification; it is about narrating the story of someone using your product.
The power of voice-to-text narration
I have found that the best way to start a JOURNEYS.md file is to stop typing. When I am trying to explain a complex flow, I use voice-to-text to talk it through with the LLM. There is something about saying the steps out loud that highlights the absurdities in a flow. If it sounds clunky when you speak it—”and then the user clicks here, then moves back to the top to find the save button”—it will feel clunky to the user.
I start by describing the “happy path” verbally: the ideal, error-free journey from A to B. I tell the AI, “The user lands on the dashboard, sees their latest broadcast stats, and clicks the ‘Generate Report’ button which triggers a slide-over panel.” Speaking it out loud helps me visualise the spatial logic of the UI. The AI then transcribes and structures this into the JOURNEYS.md file, giving me a solid baseline to critique.
The collaborative back-and-forth
Building the journey is rarely a one-way street. Once the AI has the happy path documented, we enter a phase of professional “poking.” This is where my experience in high-stakes live broadcast environments pays off. I look at the journey and ask the AI: “What happens if the stream key is invalid? Where is the error state?”
The AI is surprisingly good at identifying side journeys once you give it the primary one. We go back and forth, adding sections to the markdown file for:
- Error States: What the user sees when things go wrong and how they get back on track.
- Edge Cases: The “what ifs” that usually get ignored until they break the build.
- Empty States: What the dashboard looks like when there is no data to show yet.
This collaborative loop ensures that JOURNEYS.md is not just a list of instructions, but a robust map of the entire user experience.
UX rigour at AI speed
By the time we finish the JOURNEYS.md file, the AI has a deep understanding of the product’s choreography. It knows which buttons lead where and what the visual feedback should be. This level of planning prevents the “Frankenstein UI” that often occurs when you ask an AI to build components in isolation.
As I move forward with this series on my markdown stack, I cannot stress enough how vital this step is. It allows you to maintain the rigour of a professional UX designer while moving at the lightning speed of an AI-powered hobbyist. In the next post, I will be looking at STACK.md and how to negotiate your technical choices with an agent that knows everything but occasionally needs a firm hand.
