Stop and Plan

Stop and Plan

Intent

Before you vibe code, vibe plan. Explore your problem, explore your solution, and improve the connection between the two.

Motivation

Coding assistants may change the resource calculus of creating code and editing code, but they don’t currently alter the rest of the system: the inputs required to understand what the software should do, and the results of running the software in production.

Those parts of the system are still best solved through continuous and ongoing conversation between the human participants of a system. Understand what their needs and expectations are, compare their understanding of the system with yours, and agree the consequences of making the change that you plan.

As you come to alter the system by generating software changes with your coding assistant, check your assumptions and whether your knowledge is up to date. Ask questions, explore consequences, identify and address major risks, and refine your understanding of the change. Use the language model to help identify the questions that are relevant to your proposed change. Encapsulate your improved understanding in a refined prompt that you use to get the assistant to generate the change.

Applicability

Use Stop and Plan in any situation where generating software—or changes to existing software—may have unintended consequences. It’s fine for the process to be a very brief pause in which you decide that you already know what you need to do, or that the risks of getting it wrong are acceptable.

Alternatively, you might decide that some of the unknown issues are best addressed if you Build a Model to show to stakeholders and get feedback, rather than by making upfront choices.

Stop and Plan is especially helpful in “maintenance” changes (in other words, making changes to software that’s already used by people), to understand how the changes might alter how people deploy, use, and support the affected software.

Consequences

Stop and Plan offers the following benefits:

• Improve your understanding of the intent and consequences of a software change.
• Socialize your improved understanding with other stakeholders and get feedback.
• Refine the instructions you give to your coding assistant.

Implementation

Gather the information you have about your proposed change, and identify gaps. You might prompt your coding assistant to Disclose Ambiguity about the problem statement, or Ask for Alternatives and explore the benefits and drawbacks of each alternative.

You might also Stop and Plan away from the coding assistant, by talking to the other people on your team to find out their understanding of the system and the proposed change, and synthesizing that information with your own understanding to refine your approach.

Example

Differentiating an App

Some of the examples in the patterns catalog describe “ResearchBuddy”, an app for reading research papers and making notes on them. There are other apps available that do the same, including the free software Zotero app, so before I decide on the feature set I need to Stop and Plan and understand how to make this unique. I ask NotebookLM for suggestions, after adding the websites for Zotero and two commercial alternatives (PapersApp and Mendeley) as sources:

I'm creating a native macOS application, ResearchBuddy, that lets people organise their bibliography of research papers and write notes on them. The basic structure is a hierarchical folder list of papers, then the reader opens a paper in a split view with a PDF reader on one side and a rich text notes field on the other side.

There are multiple apps already in this area, including Mendeley, Papers, and Zotero. I intend for ResearchBuddy to support casual researchers—people who read papers to stay up to date with an area of interest or that's relevant for their work, but who aren't themselves researchers and don't need to track all the developments in a field.

What would be some features, or changes to the user experience, that could differentiate ResearchBuddy and make it more compelling for its intended customers?

The model suggests a direction:

**De-emphasize citation formatting and focus purely on reading.**
The sources show that existing tools are heavily geared toward academic output.
Papers boasts over 10,000 citation styles for formatting bibliographies, Zotero
supports over 9,000 styles for text editors like Word and Google Docs, and
Mendeley relies on its "Mendeley Cite" plugin to support users from "first
addition to final submission". Since your target audience consists of casual
researchers who do not need to publish, **removing cluttered citation and
bibliography generators** will immediately simplify the user interface and
differentiate your app from these heavy, academically focused competitors.

**Prioritize reading comprehension over academic impact metrics.**
Academic apps focus on tracking the influence and validity of research. For
instance, Papers includes tools to measure academic impact using Altmetrics and
Retraction Watch. Casual readers, however, are likely more concerned with
understanding dense material outside their direct expertise. You could differentiate
ResearchBuddy by integrating tools specifically designed for learning, similar to
Papers' **"AI Assistant," which helps users "comprehend unfamiliar disciplines or
languages" and includes a "Chat with a PDF" feature** to answer contextual questions.
Translating this into your split-view design could allow users to seamlessly question
a document on one side while taking rich text notes on the other.

**Streamline the capture of non-traditional research sources.**
Casual researchers often gather information from a mix of formal papers and mainstream
articles. Zotero differentiates itself by allowing users to **"Collect with a click,"
automatically sensing and importing research from the web, whether it is a formal
preprint from arXiv or a news story from the New York Times**. Building a similar,
frictionless web importer tailored for casual reading—rather than focusing on importing
supplemental data or complex metadata matching like Papers—would highly appeal to your
target market.

**Lean into a clean, independent organizational structure.**
Competitors offer highly complex organization systems designed for massive libraries.
Papers uses custom fields, labels, "smart collections," and watch folders, while Zotero
relies on saved searches and tags. By sticking strictly to your proposed **simple
hierarchical folder list and a split-view rich text editor**, you provide a
distraction-free environment that avoids the overwhelming "desktop clutter" associate
with professional reference managers.

**Offer local privacy and skip enterprise collaboration.**
Existing platforms heavily push cloud sync and team features. Mendeley highlights its
"2GB of free storage", Papers pushes private shared libraries for remote teams of up
to 25 users, and Zotero allows you to build collaborative bibliographies and distribute
course materials. *Please note that the following is an insight based on information
outside of the provided sources and you may want to independently verify it:* As a native
macOS application, you could differentiate ResearchBuddy by making it a purely local,
offline-first application. Emphasizing data privacy and native speed—rather than complex
cloud syncing and team collaboration—often strongly appeals to macOS users who want a
simple, personal workspace.

These feature suggestions aren't necessarily things that customers actually want, so my plan needs to target validating the candidate features, not building the software. I ask a follow up question to turn this feature list into a market research plan:

Can you create a plan I could follow to validate the UX and features in the proposal you generated with potential customers?

**Phase 1: Identify and Interview the "Casual Researcher"**
Before building the app, you need to confirm that casual readers actually feel
overwhelmed by existing tools. Interview professionals and enthusiasts who read
research but do not publish. Ask them if they currently use tools like Mendeley,
which are heavily geared toward the academic journey from "first addition to
final submission". Validate whether features like Zotero's 9,000 citation styles
or Papers' 10,000+ formatting styles feel like unnecessary clutter to them. 

**Phase 2: Test the "Frictionless Capture" Workflow**
Casual researchers often pull from diverse, non-academic sources. You can
validate your simplified capture concept by observing how users currently
save articles. Ask them to save a mix of formal papers and mainstream articles,
and see if they prefer a streamlined experience similar to Zotero's "Collect
with a click", which automatically senses and imports content ranging from
arXiv.org preprints to New York Times news stories. You want to confirm they
prefer this over heavy, academic data importing like Papers' "Metadata Matching,"
which automatically hunts for supplemental data and linked citations.

**Phase 3: Prototype the Split-View and AI Comprehension Tools**
Create a low-fidelity mockup of your proposed split-view interface featuring
the PDF on one side and rich text notes on the other. Introduce the concept of
the premium AI features we discussed. Ask your testers if an "AI Assistant" would
actively help them "comprehend unfamiliar disciplines or languages". **Specifically
validate their willingness to pay a subscription** for the ability to "Chat with
a PDF" to ask questions and receive contextual answers about dense literature. 

**Phase 4: Assess Privacy vs. Syncing Preferences**
Since ResearchBuddy will be an AGPL 3.0, offline-first macOS app, validate how much
your target audience cares about data sovereignty. Pitch them the privacy angle to
see if they value staying in control of their own data without a company having a
"financial interest in your private information," which is a key selling point for
Zotero. At the same time, **validate your freemium monetization strategy** by asking
if they would eventually pay to "Upgrade Storage" for secure "cross-device syncing"
once their library grows across multiple Apple devices. 

*Would you like me to generate a tailored report outlining this UX validation plan in a more formal document format?*

The model creates a four-step plan, of which writing code is the third step---and then, only to Build a Model of the proposed software.

Related Patterns

Disclose Ambiguity to find gaps in your understanding of a problem.

Ask for Alternatives to explore potential solutions.

Remember What We Did to record your plan and the refinements you make.