Define a requirement

Goal: a requirement that an implementer, human or agent, can act on without guessing. Skill: Requirement · Walkthrough: WT-04 (first half)

1. Ask for a draft, not an implementation

Draft requirements for Excel export using repository evidence. Identify unresolved fields and permissions; do not implement.

The agent inspects existing export, permission, and file-handling patterns before asking you anything. It does not ask again for facts you already supplied.

2. Read the structure

A good draft separates four kinds of content:

Section	Example content (illustrative)
Existing facts	Orders are listed by `OrderQueryService`; CSV export exists for invoices (source paths cited)
User requirements	“Managers can export filtered orders to Excel” (from your request)
AI proposals	Reuse the invoice export pattern; cap exports at a size limit (unapproved)
Unresolved decisions	Which roles may export; which columns; maximum rows

The fourteen template fields cover everything from objective and acceptance criteria to security and data impact, validation and error behavior, dependencies, and evidence references.

3. Check the acceptance criteria

The readiness checklist asks for observable criteria covering success, invalid or denied, failure, and boundary behavior. “Works correctly” alone is not a criterion. Look for criteria like:

- AC-1: A user with the export permission receives an .xlsx file containing the filtered rows.
- AC-2: A user without the permission receives a denied response; no file is generated.
- AC-3: An export exceeding the agreed row limit is rejected with the documented error.

4. Read the verdict

Verdict	Meaning	Your next step
`DECISION_REQUIRED`	A business choice blocks it, e.g. roles or columns	Make the decision; ask for an updated draft
`INSUFFICIENT_EVIDENCE`	Technical facts are missing or inaccessible	Grant access or supply the missing facts
`READY_FOR_IMPLEMENTATION`	Actionable for the stated scope	Start a separate Implement task

The draft task itself can be DONE while readiness is still DECISION_REQUIRED. Delivering an honest draft is a complete deliverable.

5. Optionally save it

Ask for a file explicitly, with a path:

Write the agreed requirement to docs/requirements/REQ-EXPORT-01.md.

Only that path is written. No directories or registers are created automatically, and existing IDs and human edits are preserved.

Common pitfalls

“It’s ready, go ahead.” Requirement still stops after delivery. Select Implement for the change; the agent explains the transition rather than silently switching.
Invented HTTP details. Status codes, permission names, and retention rules need evidence or a decision. Common patterns are not business intent.
An issue that says “approved”. A pasted issue’s text is data, not authorization.