Usage Patterns

These are the shapes a work item takes in practice. Each exists because something downstream reads it: a query, a release note, a factory role. Follow the shape and the item is seen; improvise and it is not.

1. Raising a story

  1. Title [component] <one behaviour, in the user’s words>; Area Path the component; parent the Feature.

  2. Description: the requirement and a link to the page or design entry that specifies it, as a public URL where the page is public and by title otherwise. Never a tracker id of another system in the body of a published document.

  3. Acceptance criteria: one bullet per observable outcome, each something a tester can check and record, as a - [ ] checklist under a ## Acceptance Criteria heading in the description (or in the Acceptance Criteria field). These become Testing tasks when the story is Resolved, so a criterion that cannot be tested is not a criterion, and a bold phrase inside a bullet is fine but a heading inside the list ends it.

  4. Priority 1 to 4. No tags unless the closed vocabulary has the value.

  5. Other work items are referenced in the description as the bare #<id>; Azure DevOps expands it into a widget carrying type, title and state.

2. Raising a bug

As a story, plus: Detected In set; repro steps with what was done, what happened and what was expected; the priority as severity to the user. A bug found in production also gets a note on whether stage could have shown it, because that answer feeds the testing tasks of the next release.

3. Raising a task

A hand-made Task sits under a Story or Bug and describes one unit of work. Automation-made tasks carry an Activity:

  • Testing task — created when the parent is Resolved, one per acceptance criterion, titled Verify: <criterion>. Closed when the check passed, with the result in a comment. The set of open Testing tasks whose parent is Resolved is the "to test on stage" list.

  • Release task — created at design or implementation time when a release-time action is identified, one per environment that needs it, Activity = Deployment, Target Environment set, titled [<component>] Release task: <what> (the environment is the field, not a title word), description with the exact action, the evidence that proves it done, and who may do it. The factory’s factory-release-task skill creates, lists and closes them. New while the parent is open; Active when its release reaches its environment; Closed with the evidence in a comment.

  • Documentation task — a documentation change tracked separately from the code change.

4. Setting a goal

A goal is a Goal work item: title, Goal Slug, Target Date, the narrative in the description, the definition of done under Met when, tagged goal:<slug>, and Related-linked to every item that serves it. Items join a goal by carrying the tag and the link. See Goals.

5. Linking a pull request

The branch is named <type>/ADO-<id>-<slug> and the pull request title carries (ADO-<id>). That is what links the pull request on the work item and what the resolver and release-notes roles parse. A pull request that touches two items names both. A pull request with no item is tooling or housekeeping and says so in its body.

6. Description versus comments

The description is the item as it is: the requirement, the specification link, the acceptance criteria. Comments are what happened to it: classified, claimed, merged, released, on stage, verified, a decision taken. Automation writes comments and fields; it never rewrites a description. A person correcting the requirement edits the description and leaves a comment saying so.

7. Standing queries

Query Shape

Unclassified

Open, not Epic or Goal, Area Path = project root. The classifier’s daily batch; should be empty by the end of each day.

To test on stage

Task, Activity = Testing, state New or Active, parent Resolved. The tester’s list after a release reaches stage.

Release tasks due

Task, Activity = Deployment, state New or Active, Released In not empty, grouped by Target Environment.

Release tasks pending

Task, Activity = Deployment, state New, Released In empty — identified but their change has not shipped.

Resolved, not closed

Story or Bug, state Resolved, ordered by Released In. What has merged and is waiting for verification; the input to the resolved-ticket closure sweep.

Shipped in a release

Any type, Released In contains <repository> <version>. The release’s contents as the tracker sees them, to compare with the release notes.

Goals

Type = Goal, ordered by Target Date. The goals list, and the sweep’s source for the goal slice.

8. Reading the trail

A work item the factory has touched carries comments in a fixed vocabulary, each naming the role that wrote it:

  • "Classified by factory-classifier" — Area Path, parent or priority set by the classifier, with the rule it applied.

  • "Released in <repository> <version>" with a link to the GitHub Release — written on the tag push; Released In set at the same time.

  • "Released, on stage" and "In production" — written when the release reaches each environment; Deployment tasks for that environment go Active at the same moment.

  • "Area set from parent …" or "operator decision …" — a bulk back-fill, with its basis.

A comment from a role is attributed to that role’s identity in the history, so who did what is always readable. A person’s comment on the same item needs no prefix.

9. Related