Work item writing standard

Standard scope

Applies to: All ADO projects under dev.azure.com/hybridcloudsolutions (base); see scope overlays below for azurelocal and tierpoint-prodtechDomain: work-items Status: Active

This standard defines how every work item in every ADO project under HCS must be authored. It covers title format, description structure, acceptance criteria, type classification, priority, dependencies, tags, area paths, and iterations.

Base rule (updated 2026-07-14 — split source of truth): this standard governs how every ADO work item is authored — title, description, Acceptance Criteria, tags, area paths, iterations — regardless of which system originated it. It does not mean ADO originates everything anymore:

• Epics, Features, User Stories, Tasks — ADO is the master. Authored directly in ADO per this standard. AB#<id> is the universal commit-link format across every scope.
• Issues, Bugs, Feature-Requests — GitHub is the master for HCS-governed repos (see github-issues.md and work-item-sync.md). They mirror UP into ADO as ADO Bug/User-Story work items for rollup and reporting — once mirrored, the ADO copy still follows this authoring standard (title/description/AC), even though we didn't control the original GitHub issue's wording.

Every ADO work item — regardless of origin — must conform to this standard before it is moved out of New state.

---

Scope overlays

The base rule above governs HCS-native delivery work. Two scopes intake and track work differently — read these before assuming the split applies everywhere:

• azurelocal overlay — GitHub Issues has been the primary intake surface for the AzureLocal org since before the estate-wide 2026-07-14 split; it now matches the base rule above rather than being an exception. Issues sync into ADO (see work-item-sync.md) and are mirrored to an AzureLocal org Project board for community visibility.
• tierpoint-prodtech overlay — GitLab Issues + Milestones is primary and authoritative for TierPoint ProdTech work. This is a firm boundary, not a phrasing difference: tierpoint-prodtech does not sync into HCS's ADO org, and the GitHub↔ADO split above does not apply there at all (TierPoint has no GitHub presence). If TierPoint has its own ADO org, it is a separate org entirely — tp work tracking stays in GitLab. Do not create HCS ADO work items to mirror tierpoint-prodtech GitLab issues, and do not expect AB#<id> links in tierpoint-prodtech commits.

Repos outside these two overlays use the base split-SoT rule as-is.

---

Title format

[scope] Concise verb-based title

• [scope] is required for cross-repo or cross-project items. For items scoped to a single repo's ADO project, omit the brackets.
• The title starts with a verb: Create, Add, Fix, Define, Migrate, Rotate, Onboard — not a noun phrase.
• Maximum 120 characters including the scope prefix.
• No trailing punctuation. No implementation details (those go in the description).

Examples:

Good	Bad
[platform] Define KV secret naming standard	KV naming
Create platform-prd-secrets ADO variable group	Variable group needs to be created for platform
[cross-repo] Onboard all AzureLocal repos to CLAUDE.md standard	CLAUDE.md
Fix deploy pipeline: missing variable group reference	Pipeline broken

---

Description

The description answers four questions in plain English:

1. What is the problem or need? One to three sentences. No jargon.
2. Why now? What is driving this — a dependency, a deadline, a compliance requirement, a user-reported issue?
3. What is in scope? Bullet list of what this item covers.
4. What is explicitly out of scope? Bullet list. This prevents scope creep and documents decisions.

Every description must be written so that someone unfamiliar with the project can understand it without asking questions.

Template:

<p>Brief explanation of the problem or need.</p>

<p>Why now: [dependency / deadline / requirement].</p>

<p><strong>In scope:</strong></p>
<ul>
  <li>...</li>
</ul>

<p><strong>Out of scope:</strong></p>
<ul>
  <li>...</li>
</ul>

---

Acceptance Criteria

Acceptance Criteria is a required field on every work item except Tasks.

An item is not Done until every acceptance criterion is met. The field is verified by the person closing the item — not assumed.

Format

Use a bulleted checklist. Each criterion must be:

• Specific and testable — "The script runs without errors on PowerShell 7.4" not "The script works."
• Observable — a person must be able to verify it by reading output, checking state, or running a command.
• One thing per bullet — do not combine two criteria into one sentence.

Given/When/Then format is acceptable for behaviour-driven criteria:

Given [context], when [action], then [outcome].

Minimum criteria count

Work item type	Minimum AC count
Epic	3
Feature	3
User Story	3
Bug	2 (repro confirmed + fix verified)
Task	Not required

Example

<ul>
  <li><code>docs/standards/keyvault.md</code> defines an env-name registry table.</li>
  <li>Every secret in kv-hcs-vault-01 uses a name from the registry.</li>
  <li>The three misnamed personal secrets are renamed and paired username secrets exist.</li>
  <li><code>mkdocs build --strict</code> passes.</li>
</ul>

---

Work item types

Type	Use when	Hierarchy	Master
Epic	Large initiative spanning multiple repos, multiple sprints, or a full quarter. Has a measurable outcome at the org or platform level.	Top of hierarchy — contains Features	ADO
Feature	A deliverable with a defined outcome, completable within one sprint cycle (≤ 4 weeks). May span repos but has a single owner. Once Approved, the roadmap-worthy ones project down to GitHub as a locked issue — see github-issues.md Delivery Stage.	Child of Epic — contains User Stories	ADO
User Story	A single unit of work tied to one repo or one system. Completable in one sprint. Has Acceptance Criteria.	Child of Feature — contains Tasks	ADO
Bug	A defect with reproducible steps, expected vs. actual behaviour, and a severity. Originates as a GitHub Issue (native Bug type) — GitHub is master; it mirrors up into ADO as a Bug work item, which still follows this authoring standard once mirrored.	Peer of User Story	GitHub (mirrors up)
Task	Sub-work inside a Story. Time-boxed. No AC required. Authored in ADO; not projected to GitHub (only approved Features get the roadmap projection).	Child of User Story or Bug	ADO

Classification rules

• If it takes more than one sprint to complete → split it into a Feature with child Stories.
• If it affects more than one repo → it is a Feature or Epic, not a Story.
• If it is a single discrete action (run a script, update a file) → Task.
• If it was reported by an external contributor via GitHub Issues → mirrors up as a Bug work item if type Bug, or as a Feature candidate (promoted to a real ADO Feature only on approval) if type Feature — see work-item-sync.md.
• If it produces a broken or wrong result → Bug, not Story.

---

Priority

ADO uses Priority 1–4. Every item must have a priority set before leaving New state.

Priority	Definition	Response expectation
1	Customer-impacting outage or security incident. Platform or production is broken right now.	Drop everything. Fix within hours.
2	Blocks committed sprint work or a dependency that stops another team. No workaround exists.	Fix within the current sprint, ideally same day.
3	Planned work scheduled for the current or next iteration. Normal sprint cadence.	Complete within the committed sprint.
4	Backlog. Valuable but not scheduled. No deadline.	Pick up when capacity allows.

Default: all newly created items start at Priority 3 unless there is a specific reason to set them otherwise.

---

Dependencies

Use ADO link types to express relationships between work items. Do not describe dependencies only in text — link them.

Link type	When to use
Predecessor	This item must be completed before the linked item can start.
Successor	This item cannot start until the linked item is done.
Related	Items share context or affect the same area but do not have a strict ordering.
Child / Parent	Hierarchical decomposition within the Epic → Feature → Story → Task chain.

Known platform dependency chain

Item	Depends on
AB#3 (variable group)	AB#9 (token in KV)
AB#9	AB#1 (SWA must exist)
AB#15 (onboard GitHub repos)	AB#13 (repo inventory — closed)
AB#16 (onboard GitLab repos)	AB#14 (GitLab inventory)
AB#23 (GitLab token)	AB#14
AB#26 (GitHub Issues migration)	AB#25 (this standard — must exist first)

---

Tags

Tags must come from the standard vocabulary below. No freeform tags. If a tag is needed that is not in this list, add it to this standard first via a PR.

Org / scope tags

Tag	Apply when
platform	Work affects the platform repo or cross-org infrastructure
azurelocal	Work affects the AzureLocal GitHub org
thisismydemo	Work affects the thisismydemo GitHub org
hybridcloudsolutions	Work affects the hybridcloudsolutions GitHub org
tierpoint	Work affects TierPoint client environments
cross-repo	Work spans more than one repo
azure-scout	Work affects the azure-scout repo (thisismydemo org)

Functional tags

Tag	Apply when
identity	Service principals, managed identities, KV secrets, PATs
pipeline	CI/CD pipelines, ADO pipeline YAML, GitHub Actions
docs	Documentation, MkDocs, README, standards
security	Security findings, credential rotation, access control
infrastructure	IaC, Bicep, Azure resources
breaking	Change breaks an existing interface or behaviour
perf	Performance improvement or regression
testing	Test authoring, test tooling setup, test coverage, quality gates
audit	Finding raised by a formal code or standards audit — the tag is what groups an audit's findings, so it stays on the item permanently
automation	Automation scripts, scheduled/unattended runs, agent-driven tooling

Product-surface tags

A product can ship through more than one surface — a PowerShell module, a CLI, a served web app — while remaining one product with one feature set. These tags say which surface a piece of work lands on. They never mean the surfaces have different capabilities: a feature that must appear on every surface is tagged cross-surface, not split into rival items.

Tag	Apply when
powershell	Work lands in the PowerShell module or script surface
cli	Command-line interaction — parameters, terminal output, progress display
web-portal	Work lands in a served web application surface
cross-surface	The capability must ship on every surface the product offers, at parity
module-enhancement	Extends a shipped module rather than adding a new deliverable
reporting	Report generation and export renderers — HTML, PDF, PPTX, Power BI, React
resilience	Error handling, retries, graceful degradation, defensive null handling
delivery	Release mechanics — versioning, packaging, tagging, gallery publishing
config	Configuration surface — settings files, manifests, parameter defaults
future-roadmap	Accepted in principle but deliberately deferred beyond the current roadmap

How to apply

Apply all tags that are relevant. A single item may carry both an org tag and a functional tag: platform, identity — work on a platform-level secret. azurelocal, docs — updating docs for an AzureLocal repo. azure-scout, cross-surface, reporting — a report export that must exist on every surface.

---

Area paths

Every ADO project has its own area paths. Within a project the hierarchy depth must be ≤ 2 levels.

Platform Engineering — approved area paths

Area path	Use for
Platform Engineering\Standards and Governance	Standard definitions, governance rules, naming conventions
Platform Engineering\Documentation	Docs site, MkDocs, README work
Platform Engineering\Identity	KV secrets, SPNs, MIs, PATs, variable groups
Platform Engineering\Pipelines	ADO pipeline YAML, GitHub Actions
Platform Engineering\Automation	Scripts, tooling, scaffolding
Platform Engineering\Integrations	GitHub ↔ ADO sync, webhooks, Logic Apps, Functions
Platform Engineering\Onboarding	Repo onboarding, standards rollout, discovery
Platform Engineering\Tooling	CLIs, dev environment, helper scripts

Do not create new area paths without a PR updating this table and the ADO project configuration.

---

Iterations and sprints

Naming pattern

<YYYY>-Q<n>-S<m>

Segment	Rules
YYYY	Four-digit year
Q<n>	Quarter: Q1–Q4
S<m>	Sprint within the quarter: S1, S2, S3 (3 sprints per quarter at 4 weeks each, or use S1–S6 at 2 weeks each)

Examples: 2026-Q2-S1, 2026-Q2-S2, 2026-Q3-S1

Cadence

• Sprint length: 2 weeks
• Sprints per quarter: 6 (S1–S6)
• Sprint backlog: locked at sprint start. No additions mid-sprint except Priority 1 or Priority 2 items.
• Backlog items: assigned to Platform Engineering root iteration (no sprint) until scheduled.

Rules

• Every item moved to Active must be assigned to a sprint iteration.
• Unscheduled backlog items remain at the project root iteration — never create a fake sprint to hold them.
• If a sprint ends with an item incomplete, move it to the next sprint and document why in the comments field.

---

Closing criteria

An ADO work item may only be moved to Closed state when:

1. All Acceptance Criteria are met and verified.
2. Any code or doc changes are committed and the pipeline has passed.
3. Linked GitHub Issues (if any) have been updated with a status comment.
4. Successor work items have been created if follow-up work was identified.

Moving an item to Closed without meeting these criteria is a standards violation.

---

Quick-reference checklist

Before saving a new work item, verify:

• [ ] Title starts with a verb and uses [scope] prefix if cross-repo
• [ ] Description has: what, why now, in scope, out of scope
• [ ] Acceptance Criteria filled in (minimum count per type)
• [ ] Type is correct (Epic / Feature / Story / Bug / Task)
• [ ] Priority is set (1–4)
• [ ] At least one tag applied
• [ ] Area path is correct and ≤ 2 levels deep
• [ ] Sprint assigned (if Active) or root iteration (if backlog)
• [ ] Dependencies linked as Predecessor / Successor / Related