Turning vague requirements into verifiable results

“Switch the framework for me” and “make it look better” can both start a conversation about work, but neither is a delivery criterion on its own. They give a direction without specifying what readers should see, where to check it, or what falls outside this round of work.

A requirement does not have to start as a complete specification. Before substantial implementation begins, it matters more to turn a vague sentence into a result that people can observe, discuss, and accept. Good requirements do not add more jargon. They let different people judge the work against the same result.

Separate what you want from how to judge it

A requirement you can deliver against needs to answer at least four questions:

1. What is the result? What content will users see, or what action will they be able to complete?
2. Where can you check it? At a public URL, in the initial HTML, through browser interactions, or in files produced by a build?
3. What is outside this round of work? Which seemingly related features, effects, or outcomes should not be inferred as part of the request?
4. Who makes the final judgment? Separate what tools can confirm from what a person needs to decide.

For example, “make the website better” can first become something like this:

Original request	Verifiable result	Explicit limits
Switch the framework for me	Opening a public URL directly shows the main content; navigation uses real links; only features that need browser behavior use scripts scoped to those features	This does not require reproducing the old framework’s entire App shell, nor does it establish improved performance or SEO
Make it look better	Headings, descriptions, and actions have a clear order on mobile; fixed heights do not cut off content; controls work with a keyboard	The color palette and whether the overall result meets expectations still need visual acceptance; this does not mean every device has been checked

The results and limits in the table matter equally. Without limits, implementers can easily add seemingly reasonable features on the requester’s behalf. Without a place to check the result, acceptance falls back to “it feels close enough.”

“Switch the framework” is not an acceptance criterion

This project originally used Vue and later moved to native Astro. If the requirement were only “switch the framework,” several very different approaches could count as complete: putting the old App inside an Astro wrapper, moving Vue components page by page, or rebuilding the page structure around Astro routes and content data.

What needs confirmation is the website’s behavior, not the framework’s name. For this work, the request became a set of results that could be checked directly:

• Opening a public URL directly returns initial HTML with the heading and main content, rather than relying on an empty browser mount point.
• Navigation uses real links so readers can go directly to other pages.
• Existing content, images, and language-specific URLs remain; the old components’ structure is not, by itself, a reason to keep it.
• Astro, HTML, and CSS handle simple page structure first. Only interactions that need browser state get additional TypeScript scoped to those interactions.

These conditions describe the actual deliverable more closely than “move the site from Vue to Astro.” They also make trade-offs discussable. If someone proposes keeping the entire old App, the question becomes whether that helps achieve these results, rather than accepting it simply because the components already exist.

Acceptance checks can inspect page HTML, deep URLs, links, and the main content with JavaScript disabled. Those checks can establish that the current page output meets the conditions. They cannot also establish that the website is faster, ranks better in search, or has every visual detail finished.

Narrow “make it look better” into interface behavior

“Better-looking” is not a useless requirement; it needs to be broken down further. If you only hand over a reference image and say “make it like this,” an implementer may treat its text, dates, buttons, and even nonexistent features as part of the specification. Those are not necessarily the intended results.

Start by rewriting the request as conditions readers can observe:

• On mobile, readers see the heading and description before the primary action. CSS order does not create a visual sequence that differs from the reading order.
• Article text stays at a readable width. Code and wide tables scroll within their own containers instead of making the whole page overflow.
• When there is no cover image or no featured article, the layout reflects the actual number of items rather than duplicating placeholder cards to fill the space.
• Interactive controls have visible focus states, and the main copy remains readable with JavaScript disabled.

DOM inspection, CSS inspection, keyboard use, and checks at different widths can verify these conditions. Whether the overall feel is right and the hierarchy feels comfortable still needs review by someone with decision-making authority. The development specification’s 320, 390, 768, 1024, and 1440 CSS px widths and 200% zoom can define a checking scope. They are not proof that “everything works on every device.”

Rewriting visual requirements as behavior does not mean reducing design to a sterile test checklist. It means clarifying the parts that affect implementation first. Keep the remaining subjective judgments explicit instead of pretending that a build result can replace them.

Add what you will not do to every requirement

Vague requirements tend to expand in two places: implementers add features, or acceptance brings in outcomes nobody originally requested. A requirement card should therefore state its exclusions too.

For this website, for example:

• “Preserve the original site” does not mean keeping every old file. First establish which content and behavior actually have publicly accessible entry points.
• “Pass the checks” does not establish visual quality, performance, SEO, traffic, or business outcomes.
• “We can start discussing it” does not commit to a fixed service offering, feature scope, or publication date.

Exclusions are not simply a way to reduce the work. They give the next decision a boundary. When a requirement needs to grow, you can add conditions explicitly instead of letting every reasonable guess quietly become a product specification.

A reusable requirement card

If you do not know where to start, use this format to organize the request. You do not need every detail settled first:

Problem to solve:
Result users should ultimately see or be able to complete:
Where the result can be observed:
Explicitly outside this round of work:
Parts tools will check:
Parts that need a person's final judgment:

“You can bring the problem even if you have not organized the requirements yet” still holds. The card does not ask the other person to finish a specification before talking. It gives the discussion a structure that can be filled in over time. Write the result before deciding whether to keep a piece of code; write the limits before deciding whether a feature is worth adding.

What reduces misunderstanding is not making requirements sound professional. It is helping the next person understand what needs to change, where to see the result, and what cannot yet be claimed.