Spec reviews
Use Spec Review to examine a requirement against a live application, then promote the resulting review into a draft workflow for repeatable automation.
Spec Review helps you explore a requirement or observed behavior before you automate it. Review findings, confirm what is testable, and promote the review into a draft workflow when you are ready to make the work repeatable.
01When to use Spec Review
Use Spec Review when you need to understand a behavior before deciding how to automate it. It is useful for:
- Reviewing a new requirement and identifying the behavior that must be verified.
- Comparing expected requirements with what the product currently does.
- Capturing exploratory findings before they become workflow steps.
- Turning a successful investigation into a repeatable draft workflow.
- Giving a team a shared starting point for test design and refinement.
Start with Spec Review when the path is not clear enough for direct workflow authoring. Use a workflow when the expected steps and checks are already well defined.
02How Spec Review works
A Spec Review gives you a structured place to examine requirements, record findings, and assess whether the behavior can be tested. Treat the review as an exploration: capture what you learn, distinguish expected behavior from observed behavior, and identify the checks that a workflow will need.
Keep the review focused on one requirement, behavior, or user journey. A focused review produces clearer findings and a more useful draft when you promote it.
Review findings and testability
Record each meaningful finding as you investigate. Describe what you checked, what happened, and why the result matters. Use findings to identify the boundaries of the behavior rather than recording only the happy path.
For each finding, consider:
- What behavior did you observe?
- Which requirement or expectation does it relate to?
- Can you reproduce the result consistently?
- What input, condition, or user action changes the result?
- What evidence would prove that a future workflow passed or failed?
Mark the behavior as testable when you can describe a repeatable action and an observable result. If a finding is not yet testable, capture what is missing, such as a clearer requirement, stable data, or an expected outcome.
Requirements and observed behavior
Separate the requirement from the current behavior. Requirements describe what should happen; observations describe what happened during the review. Keeping these distinct makes gaps, regressions, and intentional differences easier to identify.
Use concise, verifiable language:
| Review detail | What to capture |
|---|---|
| Requirement | The expected result or rule to validate |
| Observed behavior | What the product did during the review |
| Difference | Any gap between the requirement and observation |
| Evidence | The result, state, or artifact that supports the finding |
| Follow-up | The decision or change needed before automation |
Resolve ambiguous findings before promoting the review. A draft workflow can preserve the exploration, but it cannot replace a clear expected result.
03Promote a review into a workflow
Promote the review when you have identified a repeatable path and the findings describe checks that can be automated. Promotion creates a draft workflow from the review, so you can continue authoring without losing the context of the investigation.
- Open the completed Spec Review.
- Confirm that the requirements, observed behavior, and findings are accurate.
- Select Promote to workflow.
- Review the generated draft workflow and its steps.
- Add or correct inputs, actions, and checks before saving the workflow.
Promotion is a starting point, not an approval of the behavior. Keep unresolved questions in the review and make the draft workflow explicit about the behavior it is intended to verify.
04Review and refine the draft workflow
Open the draft workflow and compare it with the original review. Make sure every important finding is represented by an action or check, and remove exploratory actions that are not needed for repeatable execution.
Refine the draft by:
- Replacing ambiguous actions with explicit steps and expected results.
- Adding inputs for values that can change between runs.
- Converting review evidence into assertions or other observable checks.
- Handling required setup and cleanup consistently.
- Naming steps so another person can understand their purpose.
- Running the workflow and using the results to correct missing or unreliable steps.
Keep the Spec Review as the record of exploration and use the workflow as the repeatable version of the validated path. If execution exposes a new requirement or behavior, update the review and then refine the workflow to match.
05Best practices
- Start with a specific requirement or behavior instead of a broad product area.
- Record expected and observed behavior separately.
- Capture evidence while you investigate, not after the review is complete.
- Test boundary conditions and failure paths when they affect the requirement.
- Promote only findings that have a clear action and observable result.
- Use meaningful names for workflow steps, inputs, and checks.
- Keep exploratory notes in the review and keep the workflow focused on repeatable execution.
- Re-run the draft workflow after each significant refinement.
- Review the workflow when the requirement or product behavior changes.