From vague request to ready ticket

Consider a ticket that says “The export is broken.” The agent could start changing code immediately, but it would first have to guess which export, what failed and what the requester expected. A readiness step turns those unknowns into a small investigation and, where needed, specific questions.

Ask the question before writing the wrong change#

Start by reading the request, related decisions and relevant code. Look for existing work that already addresses the problem. Then check whether the task identifies the desired behaviour, what is outside its scope, dependencies and how the result should be tested. These are useful readiness criteria, not a reason to require a long form for every small fix.

Show the full-size diagram, and pan Back to the phone layout

In this illustrative export case, the investigation might find two reports with similar names. A useful question names them and asks which one failed. If the request includes a sample file but no expected result, ask which column or value is wrong. Avoid a generic message such as “Please provide more context”.

Ask only about matters the agent could not resolve from appropriate sources. The requester should not have to identify a Java class that the agent can find itself. Conversely, the current implementation cannot decide a new business rule merely by showing what the code does today.

Write questions in the requester’s language and distinguish them from decisions already made. Make an automated assessment identifiable and provide a route to a person. Returning a task with a necessary question is a valid result; guessing so that the task can be marked ready is not.

A bug report is not yet a verified coding task

For a bug that can be reproduced in code, investigate before dispatching a fix. Save the original report immediately, check the reported and current versions, look for matching existing work, then construct a small reproduction with an agreed expected result. Attach that evidence to an existing task or prepare a new one. An issue tracker can hold unverified reports as well as ready work; the distinction matters more than whether an issue already exists.

This adapts the feedback workflow discussed in Software Factory Design Patterns. The speakers explicitly limit that route to clear code reproductions and describe parts of their classification and deduplication work as still under evaluation. It is not evidence that a general-purpose agent can reliably classify every bug, or that every feature request needs a failing test first.

For the export example, record an invented input that splits one CSV column incorrectly, the expected columns, the code revision, relevant environment settings and the command and assertion that demonstrate the difference. Check a suspected duplicate against that evidence. Similar titles help find candidates; they do not establish the same defect.

Try it: change the evidence behind an export report

A user reports an incorrectly split CSV column. What does the investigation establish? Current code failsOld fails; current passesSimilar title, different inputExternal service unavailable

There is a concrete defect to triage.

1. Save the reported behaviour and agreed expected output.
2. Run a small invented input on a recorded current revision and preserve the failing assertion.
3. Compare existing reproductions, then attach the evidence to the matching task or create a ready coding task.

The reproduction narrows the work; it does not decide priority, authorise a deployment or prove the proposed fix.

Invented CSV report and proposed routing rules. No issue tracker, code or external service is accessed. Choose another case to see why the next action changes.

Keep “not reproduced”, “check could not run” and “passes on the checked current revision” separate. A flaky failure or a missing external dependency can make a real problem disappear from one run. Preserve the report and route the unresolved question to a person rather than marking it invalid. The environment guide explains how a setup blocker differs from an application failure.

An agent-generated reproduction is still code to inspect and run with restricted access. Rewriting an untrusted report does not make it safe. Once a reproduction is accepted, retain it as a regression check and rerun it against the candidate fix. A test passing on another branch is not evidence for the revision being reviewed.

Give the coding agent the findings it needs#

A context pack is the information prepared for the next step. For this task it can include the agreed requirement, the relevant report handler and tests, an example input and expected output, dependencies and any unresolved risks. Include the requirement version and the code revision inspected so the builder can detect later changes.

The pack should make the next investigation easier, not claim that the coding agent never needs to read another file. Link to the underlying records. A summary can omit an exception, and file paths can become outdated.

A consistent format lets ordinary code detect missing fields before implementation starts. For example, require a goal, acceptance criteria and a proposed check, and explicitly mark unknown dependencies. This can be structured data or Markdown with validated sections. A schema detects missing or malformed information; it cannot prove that a plausible acceptance criterion is correct.

Keeping a specification current explains how the agreed behaviour survives this one task. The builder guide follows what happens when the prepared task reaches implementation.

Do not maintain two conflicting specifications#

A generated spec.md can give a run a stable copy of the agreed requirements. The problem starts when someone changes the ticket while someone else edits the generated file. The builder now has two credible but different instructions.

Choose where accepted requirements are maintained. This may be a ticket, a versioned specification file or a requirements tool. A generated run copy should name the source and the version it came from. Change the maintained source, then regenerate the copy. Keep the old copy with the run that actually used it.

This derived copy is sometimes called a projection. The important property is simple: you can trace it back to the agreed record and reproduce it. It is not a second place where people independently decide what the software should do.

Larger projects may need approved sets of requirement versions, links across many tasks or product variants. IBM’s requirements-management products illustrate those capabilities. OMG’s ReqIF standard addresses exchanging structured requirements between tools. Neither implies that a small factory needs a dedicated requirements product.

Keep design reasoning separate from the obligation. In an illustrative example, requirement R-142 says an export of 100,000 rows must finish within two minutes. ADR-017 explains why the implementation streams chunks rather than assembling everything in memory. Another design may later replace that choice while the requirement stays unchanged. An architecture decision record preserves the reasoning without confusing it with the required outcome.

Keep the original request and later decisions separate#

In this workflow, the readiness agent adds its questions and assessment alongside the original request. It does not replace the requester’s description with its own interpretation. The original text records what was asked; the later decision record shows what was actually agreed. Both may be needed to understand a disagreement.

Enforce that rule in the available operations. Some systems support field-level permissions. Others need a restricted tool or gateway that permits adding an assessment but rejects changes to the original description. Do not assume that every issue tracker can enforce this through a credential alone.

The restriction also helps when a ticket contains hostile instructions. The prompt-injection guide explains why the task’s text must not grant itself extra permissions.

A request can be detailed and still suggest the wrong solution. A requested button might belong elsewhere, or the intended behaviour might conflict with an existing product rule. Explain the concern and propose an alternative for a person to decide. Do not silently turn an agent’s design preference into the accepted requirement. The human-review guide explains how to make the later acceptance decision equally explicit.

Questions people also ask

6 QUESTIONS

▸ Why does request quality matter to a software factory?

Code and tests can both follow the same mistaken interpretation. A readiness check tries to find missing decisions before that happens. It cannot eliminate every misunderstanding, and it should not ask a requester to repeat information already available in the code or project records.

▸ Should the readiness check read the code or just the ticket?

For a change to existing software, inspect the relevant code as well as the request. It can reveal an existing implementation, a dependency or a mistaken assumption about where the behaviour lives. A complete-looking ticket alone cannot establish those things.

▸ Should spec.md be the source of truth for an agent?

A maintained spec can be the agreed requirements record. But when spec.md is generated for one run from a ticket or another record, keep it as a versioned copy of that source. Update the original requirement and regenerate the copy rather than editing both independently.

▸ How is a requirement different from an architecture decision record?

A requirement describes what the software must do or what constraint it must meet. An architecture decision record explains why a particular design was chosen. The design can change while the requirement stays the same, so link the two without treating them as interchangeable.

▸ Should a request that spans several services be split automatically?

No. Check whether the pieces can be tested and released independently, whether intermediate versions remain compatible and who owns the work. Sometimes separate tasks help; sometimes they hide a dependency that must be coordinated. The number of services alone does not decide it.

▸ What happens when the requested design looks wrong?

Explain the problem and propose an alternative for the responsible person to decide. A requester may describe a symptom as a suggested button or screen change. Do not silently replace that request, but do not implement a known mistake merely because its wording is precise.