Reviewing Your Test Specs

Before converting anything, look at what you have. Discovery can produce dozens of test specifications of varying quality, and they are not equally ready to become tests. Reviewing them first tells you which ones will convert cleanly, which ones need a human decision, and which ones have no usable test content at all.

The conversion prompt does this for you. Run generate-tests-from-specs and leave the spec paths blank, and the agent reviews the bundle with you before anything is generated. You can also ask for the same information directly at any time.

Reviewing the bundle

Point the agent at the Test-Specs folder in your Cycle project, either through the prompt or in your own words.

You say:

Review the test specs in C:\CycleProjects\WarehouseSuite\Test-Specs and tell me which are worth converting.

The agent:

1. Reads the folder, separating the test specifications from the reports Discovery wrote at the root, such as Executive-Summary.md and Duplicate-Detection.txt.
2. Summarizes the specifications as counts, grouped by readiness category and crossed with review status, leading with the most convertible group. A bundle can hold hundreds of specifications, so the agent does not list them all. You narrow down from the summary.
3. Reads any individual specification you ask about in full, including its description, ordered steps, test data, and the reasons behind its readiness category.

The summary reports counts rather than a list, so it stays readable on a large bundle. It reports something along these lines:

Test-Specs: 128 specifications, 5 reports

  executable   94   (reviewed 71, pending 23)
  incomplete   27   (reviewed 4,  pending 23)
  empty         7   (reviewed 0,  pending 7)

  Reports: Executive-Summary.md, Verbose-Detail.md, Input-Sources.txt,
           Duplicate-Detection.txt, Repair-Log.md

The exact wording depends on which agent you use. What matters is the shape: the readiness categories crossed with review status, and the reports held separate from the specifications.

Reviewing is read-only. Nothing is converted or modified at this stage.

No specifications found

If the folder holds no test specifications, the agent tells you so and stops rather than inventing any. Run a Discovery document ingest first to produce a bundle.

Reading the readiness categories

The agent classifies every specification into one of three categories, judged from its content alone.

Category	Meaning	What to do
executable	The specification has both a description and at least one numbered step.	Convert it. This is the material the flow is designed for.
incomplete	The specification has a description or numbered steps, but not both.	Convert it if it has steps, and expect open questions. If it has only a description, it becomes a stub.
empty	The specification has neither a description nor numbered steps, or it could not be read.	Set it aside. There is nothing to convert. Fix the source material or drop the specification.

The category is deterministic. The same specification always produces the same category, so the listing is stable across runs and consistent between teammates.

Readiness is not review status

Readiness and review status are independent. Readiness describes whether the specification has enough content to convert. Review status is the value recorded in the specification itself during Discovery, reported exactly as written. A specification can be marked reviewed and still be incomplete, and a specification nobody has reviewed can be perfectly executable.

Choosing what to convert

Work in batches rather than converting everything at once. A batch you can review in one sitting keeps the quality high, and the coverage record means a later batch never repeats work already done.

A practical order:

1. Start with the executable specifications: They convert with the fewest open questions and give you working tests early.
2. Take the incomplete specifications that have steps next: These convert into real tests, but the agent flags what it could not determine so you can fill the gaps deliberately.
3. Triage the rest: An incomplete specification with only a description, and anything empty, needs the source documentation improved before it is worth converting. Generating a stub for it records the gap without pretending the test exists.

When you drive this through the conversion prompt, the agent carries your candidate set forward automatically. Working in your own words instead, note the bundle-relative paths of the specifications you choose, because those paths are what you pass to the prompt.

Duplicates and work already done

Two checks happen before anything is generated, and both narrow your selection rather than changing how tests are produced.

The readiness category judges one specification at a time and does not detect overlap between specifications. So the agent reads Duplicate-Detection.txt from the bundle and flags specifications in your candidate set that look like near-duplicates of one another, recommending you convert a single representative of each cluster.

The agent then checks the target directory for work already done and excludes any specification an existing test already covers.

Neither check alters the one-test-per-specification rule. Every specification you keep still becomes exactly one test.

Approve the final list

The agent restates the specifications it intends to convert and waits for your approval before generating anything. Read that list. It is the cheapest point to correct a selection.