| title | Define Stage |
|---|---|
| description | The workflow stage that captures, routes, refines, and plans work at the correct issue altitude. |
Define is the first stage of the Agent Workflow. It takes something someone wants — a feature, a bug, an improvement, external feedback, or a production signal — and routes it to the correct native issue type. The stage hands off an Epic or PBI ready to coordinate and decompose, or a Task or Bug ready for delivery. Define plans work; it does not build it.
Capture a desire for change, write an issue, plan work, decompose an epic, refine a bug report, create sub-issues, structure a feature request, or turn feedback into a task.
A description of a desired change, a feedback issue from a non-contributor (treated as input, never modified), a platform signal (error, failed run, alert), or an existing issue to refine.
Turn the input into an issue with a provisional native type and enough local context to refine it.
- Search for duplicates first — propose consolidation rather than creating a new issue.
- Follow the universal Issue Format and the selected type page for its body.
- Acceptance criteria must be user-observable and testable.
Ground the issue so anyone reading it agrees on what "done" means, up to the Definition of Ready.
- Pain before solution — push back on implementation-framed requests.
- Make assumptions explicit.
- Acceptance criteria answerable yes or no by a non-author.
- Ask one question at a time when interactive.
Decide how the work will happen and record the decisions.
- Route the work through the Issue Hierarchy; do not infer altitude from effort, priority, or a legacy label.
- For an Epic or PBI, establish native containment and dependency relationships and refine the first required children to their own readiness gates.
- For a Task or Bug, produce one executable delivery plan sized for one pull request. Use the audited operational Task path only when no repository artifact exists.
- Find the minimum viable path — spike, then proof of concept, then minimum viable product, then improve.
- Record decisions at the issue's planning altitude, with rationale and alternatives where they matter.
- Resolve open questions before finishing; defer anything that does not block this slice to a follow-up issue.
- Tone is impersonal. The issue description is the source of truth; comments record what changed.
- External references are hyperlinks.
- Do not modify a feedback issue from a non-contributor — create an internal issue and cross-link.
- Stop when the issue meets the readiness gate for its altitude. Hand a ready delivery leaf to the Implement stage; do not build, branch, or open pull requests here.
- Workflow — the loop this opens.
- Issue Format, Issue Planning, Issue Relationships, and Issue Hierarchy — canonical issue ownership.
- Definition of Ready and Done — the readiness bar this aims for.