Vibe GuideWrite requirements and stories
Requirements record inputs, actions and expected outcomes.
Why this milestone?
Write agreed features down so you can check the implementation later.
Start here2 steps · Follow in order
0102Keep the agreement in plain languageTo checkOpen this stepClose this step
01What do you need, and what should you keep?
Your agreed first-version feature list.
The next step can describe use based on this file.
Which files should AI read and save in this step?
In your tool’s project chat, ask it to open the files below. If a file is missing, follow the link back to the step that creates it.
Ask AI to read these materials first: idea.md · docs/requirements.md
Ask AI to save the result to: docs/requirements.md
Missing these materials? Return to the step that creates them →
02What will this step help you do?
Write agreed features down so you can check the implementation later.
Understand it, then judge for yourself
What does this concept mean?
Requirements record inputs, actions and expected outcomes.
How would you decide in a different situation?
If you only write “easy to use”, will someone know which actions and results count as a pass?
See a reference answer
No. Replace subjective quality with actions and observable outcomes such as duplicate requests not reserving twice.
Answer in your own words; if unsure, compare the explanation above and check it against your own project.
03What exactly should you do in this step?
OpenClose
docs/requirements.md in the project
Send one action at a time: select and copy its prompt (⌘C on Mac, Ctrl+C on Windows), switch to your tool’s project chat, paste it, replace bracketed fields and send. Wait for the reply and check the stated result before continuing.
Describe each feature as input, action and visible result.OpenClose
Suggested prompt:
Read docs/requirements.md. Give each required feature an ID, inputs, actions, normal results and failure messages for my review.
Afterwards, you should see: Every feature has an observable result.
Compare with your idea and save the reviewed version.OpenClose
Suggested prompt:
Update docs/requirements.md with confirmed content and a practical check for each feature. Do not add unrequested features.
Afterwards, you should see: The next step can describe use based on this file.
Practice: personal journal (frontend + backend + database)
Use the same learning-journal project throughout this example. For your own project, compare applicable requirements without creating another project.
Review title length 1–80 and body 1–2000 after trimming. Clear input only after a successful save.
- What should you see after this step?
- Unavailable service preserves input; backend independently rejects blank and oversized fields.
- What should you do first if you get stuck?
- If requirements merely say clickable, specify failed saves, offline behavior and blank input.
04Not sure how? Follow each action
OpenClose
Describe each feature as input, action and visible result.
- What should you see after this action?
- Every feature has an observable result.
- What should you do if that result is missing?
- Replace vague claims like good experience with specific behavior.
Compare with your idea and save the reviewed version.
- What should you see after this action?
- The next step can describe use based on this file.
- What should you do if that result is missing?
- Ask for an explanation before approving unclear items.
05Words in this step
OpenClose
PRD — Product requirements document ↗
Records agreed features, rules, and acceptance conditions.
Like an agreed renovation requirements list.
Acceptance criteria ↗
Observable conditions used to accept completed work.
Instead of “fast service,” require a collection number after payment.
06How should you handle a problem here?
OpenClose
The document is too long to review
- Where should you look to understand the problem?
- Find the section for the first user flow.
- Follow these steps to resolve the problem
- Ask AI for three to five decisions that need personal input, with concrete examples. Keep supporting detail in the file.
- Expected recovery
- The scope and result can be personally confirmed, with unknowns left visible.
Edit the template with actual material, confirm, then copy into the current project conversation. Mark unknowns as undecided and replace examples as needed.
Confirmed · personalized content ready to copy
I am at “Keep the agreement in plain language”. Expected: Each main action has an expected result and an error response.. Actual screen/error: [add here]. Inspect existing files first. Give one reversible action at a time, its location, and expected result. Do not recreate the project or delete existing work.07Material for this step (fill or copy)
OpenClose
If you completed the individual prompts above, do not resend this full template. Use it to organize this step’s material when needed; replace bracketed fields, confirm and copy into the project chat.
Edit the template with actual material, confirm, then copy into the current project conversation. Mark unknowns as undecided and replace examples as needed.
Confirmed · personalized content ready to copy
First check access to idea.md, docs/requirements.md. If missing or inaccessible, identify the prerequisite and owner action, then stop rather than invent prior work.
Read idea.md and the confirmed scope in docs/requirements.md. Complete only requirements: inputs, actions, results, applicable failures and passing criteria. Preserve unknowns; do not add storage, login or cloud services without a requirement. Save and read back the document, reporting changes and questions. Do not write stories, technical plans or code in this step.Journal practice: fill or supplement this step
For this full-stack practice only: use this combined prompt, fill its fields and send it once instead of also sending the generic template. It does not authorize later steps.
Edit the template with actual material, confirm, then copy into the current project conversation. Mark unknowns as undecided and replace examples as needed.
Confirmed · personalized content ready to copy
First check access to idea.md, docs/requirements.md. If missing or inaccessible, identify the prerequisite and owner action, then stop rather than invent prior work.
Read idea.md and the confirmed scope in docs/requirements.md. Complete only requirements: inputs, actions, results, applicable failures and passing criteria. Preserve unknowns; do not add storage, login or cloud services without a requirement. Save and read back the document, reporting changes and questions. Do not write stories, technical plans or code in this step.
I selected the full-stack journal practice.
Specify agreed R1–R3 input limits, disabled pending button, preserved failed input and refreshed successful list. Requirements only, no code.08Check this before continuing
Each main action has an expected result and an error response.
09What should you do if the expected result is missing?
OpenClose
Replace vague claims like good experience with specific behavior.
Compare with an example (illustration, not your result)
Weak: easy booking. Clear: R01 capacity 20, success reduces remaining places by one; duplicates do not consume extra places; full sessions reject booking.
0202Describe how people will use itTo checkOpen this stepClose this step
01What do you need, and what should you keep?
The requirements document saved in your project.
The sequence connects and the file opens.
Which files should AI read and save in this step?
In your tool’s project chat, ask it to open the files below. If a file is missing, follow the link back to the step that creates it.
Ask AI to read these materials first: idea.md · docs/requirements.md
Ask AI to save the result to: docs/stories.md
Missing these materials? Return to the step that creates them →
02What will this step help you do?
Write the whole user journey to discover missing actions.
Understand it, then judge for yourself
What does this concept mean?
A user story names who needs what; the journey gives the actions in order.
How would you decide in a different situation?
Which is easier to check: “supports saving” or “the original text remains after reopening”?
See a reference answer
The second is testable; also specify same-device or cross-device behavior.
Answer in your own words; if unsure, compare the explanation above and check it against your own project.
03What exactly should you do in this step?
OpenClose
Project chat and docs/requirements.md
Send one action at a time: select and copy its prompt (⌘C on Mac, Ctrl+C on Windows), switch to your tool’s project chat, paste it, replace bracketed fields and send. Wait for the reply and check the stated result before continuing.
Describe a person using the project from start to finish.OpenClose
Suggested prompt:
Read idea.md and docs/requirements.md. Write each user’s complete journey, one action at a time, including recovery from errors. Do not build yet.
Afterwards, you should see: You can picture a real person following the sequence.
Read it as a user, fill gaps and save.OpenClose
Suggested prompt:
Save the confirmed journeys to docs/stories.md with their requirement IDs.
Afterwards, you should see: The sequence connects and the file opens.
Practice: personal journal (frontend + backend + database)
Use the same learning-journal project throughout this example. For your own project, compare applicable requirements without creating another project.
Describe opening the journal, writing today’s learning, saving and finding it the next day.
- What should you see after this step?
- docs/stories.md covers successful saving and retry after failure.
- What should you do first if you get stuck?
- A database insert is not a user action; the learner clicks and reads the page.
04Not sure how? Follow each action
OpenClose
Describe a person using the project from start to finish.
- What should you see after this action?
- You can picture a real person following the sequence.
- What should you do if that result is missing?
- Explain any account or page that appears without an introduction.
Read it as a user, fill gaps and save.
- What should you see after this action?
- The sequence connects and the file opens.
- What should you do if that result is missing?
- Fill missing actions such as where payment starts before saying it succeeded.
05Words in this step
OpenClose
User story ↗
A need stated from a user's perspective with its purpose.
As a commuter, reserve breakfast to avoid queues.
User flow ↗
The actions connecting a user's start and goal.
Enter, choose, pay, collect.
06How should you handle a problem here?
OpenClose
AI lists features without a user flow
- Where should you look to understand the problem?
- Check one story for prerequisites, actions and results.
- Follow these steps to resolve the problem
- Reply: “Rewrite the first feature as a person’s real flow, with normal and failed outcomes, without adding features.”
- Expected recovery
- Repeat the original action and obtain the expected result; keep unexecuted checks marked unverified.
Edit the template with actual material, confirm, then copy into the current project conversation. Mark unknowns as undecided and replace examples as needed.
Confirmed · personalized content ready to copy
I am at “Describe how people will use it”. Expected: Each first-version feature maps to a user action and acceptance criteria.. Actual screen/error: [add here]. Inspect existing files first. Give one reversible action at a time, its location, and expected result. Do not recreate the project or delete existing work.07Material for this step (fill or copy)
OpenClose
If you completed the individual prompts above, do not resend this full template. Use it to organize this step’s material when needed; replace bracketed fields, confirm and copy into the project chat.
Edit the template with actual material, confirm, then copy into the current project conversation. Mark unknowns as undecided and replace examples as needed.
Confirmed · personalized content ready to copy
First check access to idea.md, docs/requirements.md. If missing or inaccessible, identify the prerequisite and owner action, then stop rather than invent prior work.
Read idea.md and docs/requirements.md. Write stories for confirmed scope: who, situation, goal and reason. Add prerequisites, actions, normal results, failure feedback and acceptance criteria. Save the stories as a separate document, docs/stories.md (do not merge them into docs/requirements.md). Mark unknowns, save and read back the file. Do not implement yet.Journal practice: fill or supplement this step
For this full-stack practice only: use this combined prompt, fill its fields and send it once instead of also sending the generic template. It does not authorize later steps.
Edit the template with actual material, confirm, then copy into the current project conversation. Mark unknowns as undecided and replace examples as needed.
Confirmed · personalized content ready to copy
First check access to idea.md, docs/requirements.md. If missing or inaccessible, identify the prerequisite and owner action, then stop rather than invent prior work.
Read idea.md and docs/requirements.md. Write stories for confirmed scope: who, situation, goal and reason. Add prerequisites, actions, normal results, failure feedback and acceptance criteria. Save the stories as a separate document, docs/stories.md (do not merge them into docs/requirements.md). Mark unknowns, save and read back the file. Do not implement yet.
I selected the full-stack journal practice.
Write create, read, blank rejection and stopped-service retry stories in docs/stories.md, linked to R1–R3.08Check this before continuing
Each first-version feature maps to a user action and acceptance criteria.
09What should you do if the expected result is missing?
OpenClose
Explain any account or page that appears without an introduction.
Compare with an example (illustration, not your result)
S01 maps to R01: open event, see availability, submit, receive confirmation; when full, remain on the page with a reason.
Words in this milestoneIn order of appearance; open for the full explanation
More troubleshooting references
Stuck? Start with what actually happens
2 situationsThese paths synthesize official docs and public reports, not frequency data. Check the symptom and verify the result.
“Good-looking and easy” cannot be tested
Observed symptom: AI and owner disagree on what completion means.
- What should you check first?
Specify trigger, input, and observable result for each feature.
- Then resolve
Convert adjectives into checks. For example, an empty required field shows a field error while preserving entered data; adapt to the actual task.
- Verify the result
Another person can decide pass or fail from the written steps.
Edit the template with actual material, confirm, then copy into the current project conversation. Mark unknowns as undecided and replace examples as needed.
Confirmed · personalized content ready to copy
I am blocked at: “Good-looking and easy” cannot be tested.
Project and tool: [name, version, and project path]
Observed behavior: [steps, exact error, or screenshot; remove secrets and personal data]
Expected result: [actual goal]
First inspect: Specify trigger, input, and observable result for each feature.
Proposed approach: Convert adjectives into checks. For example, an empty required field shows a field error while preserving entered data; adapt to the actual task.
Explain the evidence and cause before making the smallest relevant fix. Preserve existing changes and do not add features. If I must act, give one precise action at a time and its expected visible result.
Success criteria: Another person can decide pass or fail from the written steps.
Report actual checks, unchecked items, and the next step.ReferencesPlaywright · Testing best practices ↗
Only the happy path is specified
Observed symptom: Empty data, failed requests, and repeated actions have no defined behavior.
- What should you check first?
Check empty input, invalid input, waiting, failure, and repeated actions.
- Then resolve
Add one normal and one failure scenario per feature, including input preservation, retry, or return behavior.
- Verify the result
Requirements define both success and failure exits.
Edit the template with actual material, confirm, then copy into the current project conversation. Mark unknowns as undecided and replace examples as needed.
Confirmed · personalized content ready to copy
I am blocked at: Only the happy path is specified.
Project and tool: [name, version, and project path]
Observed behavior: [steps, exact error, or screenshot; remove secrets and personal data]
Expected result: [actual goal]
First inspect: Check empty input, invalid input, waiting, failure, and repeated actions.
Proposed approach: Add one normal and one failure scenario per feature, including input preservation, retry, or return behavior.
Explain the evidence and cause before making the smallest relevant fix. Preserve existing changes and do not add features. If I must act, give one precise action at a time and its expected visible result.
Success criteria: Requirements define both success and failure exits.
Report actual checks, unchecked items, and the next step.ReferencesPlaywright · Testing best practices ↗
References for this milestone
Open these when the question arises; they are not extra required actions.
- How can AI stay on task?
When sending a new task, requesting an edit or reporting an error.
My project material and backups
Material stays in this browser, not in project files or AI chat. Chinese and English template drafts are separate; project selection and progress are shared. Do not enter passwords or API keys here.
Includes idea, progress, template drafts, personal checks and selection conditions, but not project code. Restore creates a new draft and preserves existing projects.
Download/import unavailable? Restore backup text
Draft and progress stay in this browser.
Complete the actions in order; expand the matching checks and remedies if you get stuck.