microsoft / microsoft/hve-core

Verify the Azure DevOps disabled-checkbox convention and reconcile the third checklist form

Open
#2,643 0 comments 1 reaction 1 assignee Claimed by @WilliamBerryiii View on GitHub
documentation priority-3 skills
Dominant language
Python
Stars
1.5k
Forks
301
Avg merge
3d 3h
Merged PRs (30d)
92

Description

## Context

PR #2602 changed the Azure DevOps Server HTML checklist guidance to emit native disabled checkboxes:

```html

  • Pending item

  • Complete item

  • ```

    This follows the convention already used by two shared authorities that write into the same Azure DevOps HTML description field, both predating that PR: the shared `backlog-templates` skill and the ADR handoff instruction. Before the change, the Azure DevOps reference instructed against the exact markup a shared skill emits for the same rendering target.

    Two things remain unverified.

    **Rendering and assistive behavior.** Whether Azure DevOps Server preserves a disabled `input` element through work-item HTML field sanitization has not been tested directly. The convention is already in production from two authorities, so following it keeps the risk in one place rather than creating a third divergent form — but nobody has confirmed the element survives, or how a screen reader announces it.

    **A third checklist form.** The shared templates render acceptance criteria as plain list items with no state prefix. The repository therefore holds three checklist forms: native disabled checkboxes, Markdown task lists where supported, and plain list items.

    ## Why this was deferred

    The accessibility finding on PR #2602 was about markup semantics, and following the existing convention resolved both that finding and an internal contradiction. Verification needs a live Azure DevOps Server instance and a screen reader, which is not something the review remediation could carry.

    ## Proposed work

    Verify the convention, then reconcile the third form.

    ## Acceptance criteria

    - [ ] A disabled checkbox is confirmed to survive Azure DevOps Server work-item HTML field sanitization, or the guidance is changed to a form that does
    - [ ] Screen-reader announcement of both pending and complete states is recorded for at least one common reader
    - [ ] The plain-list acceptance-criteria form in the shared templates is either reconciled with the checkbox convention or documented as intentionally different
    - [ ] The findings are written into the Azure DevOps reference so the next author does not repeat the investigation

    ## Evidence

    - PR #2602 review threads covering checklist accessibility
    - `.github/skills/project-planning/backlog-management/references/ado.md` — HTML rendering section
    - `.github/skills/shared/backlog-templates/SKILL.md` — Azure DevOps HTML work-item template
    - `.github/instructions/project-planning/adr-handoff.instructions.md` — Azure DevOps work-item template

    Contributor guide

    Open the contributing guide

    Assessment

    This issue has not been assessed yet.

    Get new issues in your inbox

    A short digest of beginner-friendly GitHub issues.