Turn a Real Problem into a Software Specification

Describe one complete useful journey before asking AI to build screens.

“Build me a catalog app” can produce search boxes, colorful cards, account pages, and an elaborate dashboard. It can also leave unanswered the most basic question: what must a user actually be able to do?

A specification turns an intention into behavior that can be built and checked. It identifies the user, inputs, data rules, allowed changes, success, and failure. Its quality is measured by how little the builder must invent about the core task.

You can begin with a small learning app. The point is to practice making decisions explicit, then observe how those decisions shape the code.

Identify the user and the smallest useful outcome

Our fictional user is a learner organizing sample item titles during one practice session. The smallest useful outcome is to add a title, see it in a list, and remove it again.

This is not yet a permanent personal archive. The prototype stores entries only in the current browser page’s memory. Reloading clears them, and the page must say so before the user enters data.

That limitation is part of the intended learning product. A real catalog intended to preserve records would need a different specification covering persistence, recovery, and access.

Write the problem in one sentence: “The learner needs a small list they can edit during a practice session to understand form validation and interface state.” That sentence gives the first build a clear purpose.

Map the whole journey

The journey begins with an empty page containing a labeled title field, an Add item button, and an empty-list message.

The learner enters a title and submits the form. The application validates it. If valid, it adds the title, updates the count, announces the result, clears the input, and returns focus to the title field. If invalid, it preserves the input, explains the problem, and puts focus on the field needing correction.

Each listed item has a Remove button whose accessible name identifies the title. Removing an item updates the list and count, announces the removal, and returns focus to the input. Reloading returns the page to its empty state.

This is one complete journey with success, correction, and recovery from a mistaken addition. It is more useful as an initial specification than a list of disconnected screens.

Define the data and matching rules

A code point is a unit of Unicode text representation, not necessarily a complete user-perceived character. This prototype uses that simple measurable rule deliberately. A multilingual production catalog may need a different length and matching policy.

The duplicate rule does not claim that all equivalent spellings or visually similar characters match. It establishes a bounded behavior the implementation can reproduce.

IDs distinguish entries internally. They are not evidence of an authenticated user, a globally unique record, or a persistent database key.

Specify permissions in the context that exists

This prototype has no accounts, server, or shared database. The person using the tab can add and remove the tab’s sample entries. There is no other user’s record to authorize in this design.

Do not add a login page to imply security that the application does not implement. If shared storage is introduced later, authentication and server-side authorization become new requirements.

Similarly, the application should not request microphone, camera, location, or contact access. None is needed for the journey.

A permission statement should describe actual boundaries. “Secure by design” is not a replacement for identifying where data lives and who can change it.

Write observable acceptance criteria

Use examples that another person can execute without guessing the intended result.

Include ordinary success and the failures most likely to confuse a user. A specification that only describes valid input leaves error behavior to invention.

For form feedback, W3C’s user-notification guidance explains the importance of understandable errors and accessible status information. The criteria here translate that concern into a small project’s observable behavior.

Define the interface’s practical constraints

The page should use semantic form controls, visible labels, readable text, and a visible keyboard focus indicator. The layout should remain usable at the chosen test widths of 390 and 1,280 CSS pixels without horizontal page overflow in the defined cases.

These checks provide useful evidence, but they do not amount to a complete accessibility audit. For a real release, expand testing according to the users and applicable requirements.

Because this application updates local state synchronously, there is no network loading state. If a future version loads records from a server, specify loading, timeout, partial failure, and retry behavior then. Do not add a fake spinner simply because many apps have one.

Use messages that describe actual actions. “Added to this list” is supported. “Saved permanently” would contradict the storage design.

Control scope and open questions

The essential version includes adding, listing, removing, counting, validation, and clear feedback. Later ideas include persistence, search, import/export, editing, and shared accounts.

Record those ideas without quietly adding them to the first build. Each changes requirements. Import introduces malformed files and duplicates. Persistence introduces storage failure and recovery. Accounts introduce identity and authorization.

An open question should have an owner or a clear decision rule. In this teaching brief, the author has chosen the matching, length, and storage rules. A real user project should obtain those decisions from the people responsible for the product.

Do not disguise a guess as user research. The fictional learner and requirements here are authored examples, not findings from interviews that were never conducted.

Prepare the implementation brief

A compact handoff reads:

“Build a single local HTML page with embedded CSS and JavaScript implementing the defined catalog journey. Use no external services or packages. Store sample entries only in page memory and display that limitation. Apply the stated title, duplicate, and capacity rules. Use semantic controls, literal text rendering, visible focus, error feedback, and status announcements. Include instructions for opening the file and a test record covering the acceptance table.”

The definition of done includes the actual functioning page, inspected code, the relevant tests, and clear status. A screenshot alone does not establish the journey.

Ask the builder to list any requirement it cannot satisfy. The useful response is an explicit gap, not an invented feature that changes the goal.

Consider whether software is needed at all

For a one-time list, paper or a spreadsheet may solve the practical problem with less work. The browser prototype is justified here as a programming lesson.

In an operational setting, compare the proposed software with the simplest adequate existing process. Include setup, maintenance, training, and recovery effort. AI can reduce some coding effort without eliminating the cost of owning the application.

If the existing tool already handles the work well, the next useful project may be clearer instructions or a small export rather than a new app.

A reusable prompt

Turn this problem into a minimal software specification with one complete user journey. Identify the user, data fields, matching rules, storage, permissions, success, correction, and failure behavior. Write observable acceptance criteria with sample inputs, accessibility checks, and a definition of done. Separate essential features, later ideas, and unresolved decisions. Do not invent user research or imply persistence, authentication, or external actions that the design does not include.

For students: trade specifications before coding

Write a brief for a small catalog or event-planning exercise using synthetic data. Give it to a classmate and ask what they would still need to decide before building.

Revise the brief to resolve those gaps. Then compare whether two independent implementations satisfy the same behavior, even if their visual designs differ.

Design students can focus on the journey and feedback. Computing students can connect data rules to validation. Students in other fields can supply a realistic task while keeping the first version small enough to inspect.

Practice: make the catalog buildable

Use the prototype decisions above to write a one-page implementation brief and a test checklist. Add one proposed later feature and explain which new requirements it introduces.

Challenge the phrase “save an item.” Replace it with wording that matches page-memory storage. Explain how the specification would change if users needed records after closing the browser.

Completion check: A builder can implement the journey without inventing core rules; valid and invalid input have observable outcomes; storage and permissions are explicit; keyboard and layout checks are defined; and the brief does not confuse a prototype with a persistent service.

Stretch: Compare the app with a paper list and a spreadsheet for a real small task. Explain which option best meets the user’s needs after including maintenance and recovery, not just initial creation time.