Skip to content

azure boards markdown bug analysis

Jump to bottom
Kazushi Kamegawa edited this page Oct 5, 2026 · 1 revision

Azure Boards Markdown Bug Analysis and Wiki Back-Links

日本語

Summary

Make the azure-devops-boards skill record a Bug's analysis (root cause and fix approach) in the field the Bug form actually shows, write long-text fields as Markdown with an HTML fallback, and link every work item registered in the Azure DevOps Wiki back to its page.

Tracking

Type Issue
Parent Issue #79
Sub-issue Issue #80
Sub-issue Issue #81
Sub-issue Issue #82

Background

The azure-devops-boards skill sometimes leaves the AI's analysis (root cause, fix approach) out of a Bug's body. It writes System.Description, which the Agile/Scrum/CMMI Bug form does not show (the Bug body is Repro Steps, Microsoft.VSTS.TCM.ReproSteps), and it converts all long-text values to HTML even though Azure Boards can now store each multiline field as Markdown (rich text/HTML remains the default and takes precedence unless the field is switched). Work items registered in the Azure DevOps Wiki also have no link back to the page.

Decisions

Topic Decision
Bug body field Repro Steps (Microsoft.VSTS.TCM.ReproSteps)
Wiki back-link Both a ## Wiki section in the body and a Hyperlink relation

Design

  1. Long-text field format (Markdown-first): write the Markdown source and add {"op":"add","path":"/multilineFieldsFormat/<FieldRef>","value":"Markdown"} in the same JSON Patch (Azure DevOps MCP: format Markdown on create / update_batch). Encode < and > as &lt; / &gt; like the MCP server does. Verify multilineFieldsFormat.<FieldRef> is Markdown (case-insensitive) on read-back. If the server rejects or ignores it (e.g., Azure DevOps Server), fall back to the existing Markdown-to-HTML conversion. Never leave raw Markdown in an HTML-format field. When updating a field stored as HTML, switch the format and rewrite the whole field.
  2. Bug analysis body: Repro Steps contains, in order, ## Repro steps, ## Expected vs actual, ## Root cause, ## Fix approach, and ## Wiki once registered. Write "Not yet analyzed" instead of omitting a section; rewrite when the analysis or the approved fix approach changes; verify sections on read-back.
  3. Wiki back-link for any work item type (Feature-equivalent, Bug, Task, others): take the page remoteUrl from the Wiki skill's read-back, add or replace a ## Wiki section in the body field, add a Hyperlink relation (skip duplicates), and verify on read-back.
  4. Update the Work Item agent, the Wiki skill handoff (return remoteUrl), the .github mirrors, CHANGELOG (EN/JA), and bump azure-devops-toolkit to 0.3.1.

Organization and project references in examples use the {org}/{project} placeholders.

Implementation phases

  1. Boards SKILL.md and the Windows-native reference (PowerShell 7 and Linux/macOS examples).
  2. Work Item agent and Wiki skill handoff.
  3. .github mirrors, CHANGELOG, version bump, and marketplace validation.

Verification

  • Confirm the multilineFieldsFormat path against the azure-devops-mcp source.
  • Statically parse the PowerShell examples.
  • Run scripts/validate_marketplaces.py.
  • Run the existing Wiki validator tests.
  • Diff the .github mirrors against the plugin copies.
  • Review consistency across files.
  • Run a live check against a test organization when one is available.

Clone this wiki locally