[Bug] Field mapping incorrect, some fields missing on backlog refinement

[djm81]

Describe the Bug

When running specfact backlog refine with Azure DevOps adapter, the Acceptance Criteria and Assignee fields are missing in the output, therefore missing important data for filtering (by assignee) and potentially loosing refinement of Acceptance Criteria (the KEY element for user story before it can be considered "Done" according to "DoD").

To Reproduce

Steps to reproduce the behavior:

# Example command that triggers the bug
specfact backlog refine ado --ado-org <org>--ado-project <project>--limit 1 --state "New" --iteration "<area path>\<year>\<sprint>" --preview

Expected Behavior

Found backlog items

Refining item of : <WORK_ITEM_TITLE>
No template detected, using resolved template: <RESOLVED_TEMPLATE_ID>

Preview Mode: Full Item Details
Title: <WORK_ITEM_TITLE>
URL: https://dev.azure.com//<PROJECT_GUID>/_apis/wit/workItems/<WORK_ITEM_ID>
State:
Provider:
Assignee:

Story Metrics:

• Story Points: <STORY_POINTS>
• Business Value: <BUSINESS_VALUE>
• Priority: (1=highest)
• Value Points (SAFe): <VALUE_POINTS>
• Work Item Type: <WORK_ITEM_TYPE>

Body:

Acceptance Criteria:

Target Template: <TEMPLATE_NAME> (ID: <TEMPLATE_ID>)
Template Description: <TEMPLATE_DESCRIPTION>

Actual Behavior

Found backlog items

Refining item of : <WORK_ITEM_TITLE>
No template detected, using resolved template: <RESOLVED_TEMPLATE_ID>

Preview Mode: Full Item Details
Title: <WORK_ITEM_TITLE>
URL: https://dev.azure.com//<PROJECT_GUID>/_apis/wit/workItems/<WORK_ITEM_ID>
State:
Provider:

Story Metrics:

• Story Points: <STORY_POINTS>
• Business Value: <BUSINESS_VALUE>
• Priority: (1=highest)
• Value Points (SAFe): <VALUE_POINTS>
• Work Item Type: <WORK_ITEM_TYPE>

Body:

Target Template: <TEMPLATE_NAME> (ID: <TEMPLATE_ID>)
Template Description: <TEMPLATE_DESCRIPTION>

Environment

• OS: Windows
• Python Version: 3.11.6
• SpecFact CLI Version: 0.26.7
• Installation Method: pip

Command Output

Include the full command output (with --verbose if applicable):

Paste command output here

Codebase Context (for brownfield issues)

If this bug occurs when analyzing legacy code:

• Project Type: [e.g., Django, Flask, FastAPI, plain Python]
• Codebase Size: [e.g., ~10K lines, ~100 files]
• Python Version in Target Codebase: [e.g., 3.8, 3.11]

Additional Context

Raw ADO JSON api output (sanitized and generalized) as example structure:

{
"id": "<WORK_ITEM_ID>",
"rev": "<REVISION_NUMBER>",
"fields": {
"System.AreaPath": "\<AREA_PATH>",
"System.TeamProject": "",
"System.IterationPath": "\\<SPRINT_NAME>",
"System.WorkItemType": "User Story",
"System.State": "New",
"System.Reason": "New",
"System.AssignedTo": {
"displayName": "<USER_DISPLAYNAME_A>",
"url": "https://<IDENTITY_HOST>/<COLLECTION_GUID>/_apis/Identities/<GUID_ASSIGNEDTO>",
"_links": {
"avatar": {
"href": "https://<ADO_HOST>//_apis/GraphProfile/MemberAvatars/aad.<AAD_TOKEN_ASSIGNEDTO>"
}
},
"id": "<GUID_ASSIGNEDTO>",
"uniqueName": "<USER_UPN_A>",
"imageUrl": "https://<ADO_HOST>//_apis/GraphProfile/MemberAvatars/aad.<AAD_TOKEN_ASSIGNEDTO>",
"descriptor": "aad.<AAD_TOKEN_ASSIGNEDTO>"
},
"System.CreatedDate": "<ISO_DATETIME_CREATED>",
"System.CreatedBy": {
"displayName": "<USER_DISPLAYNAME_B>",
"url": "https://<IDENTITY_HOST>/<COLLECTION_GUID>/_apis/Identities/<GUID_CREATEDBY>",
"_links": {
"avatar": {
"href": "https://<ADO_HOST>//_apis/GraphProfile/MemberAvatars/aad.<AAD_TOKEN_CREATEDBY>"
}
},
"id": "<GUID_CREATEDBY>",
"uniqueName": "<USER_UPN_B>",
"imageUrl": "https://<ADO_HOST>//_apis/GraphProfile/MemberAvatars/aad.<AAD_TOKEN_CREATEDBY>",
"descriptor": "aad.<AAD_TOKEN_CREATEDBY>"
},
"System.ChangedDate": "<ISO_DATETIME_CHANGED>",
"System.ChangedBy": {
"displayName": "<USER_DISPLAYNAME_C>",
"url": "https://<IDENTITY_HOST>/<COLLECTION_GUID>/_apis/Identities/<GUID_CHANGEDBY>",
"_links": {
"avatar": {
"href": "https://<ADO_HOST>//_apis/GraphProfile/MemberAvatars/aad.<AAD_TOKEN_CHANGEDBY>"
}
},
"id": "<GUID_CHANGEDBY>",
"uniqueName": "<USER_UPN_C>",
"imageUrl": "https://<ADO_HOST>//_apis/GraphProfile/MemberAvatars/aad.<AAD_TOKEN_CHANGEDBY>",
"descriptor": "aad.<AAD_TOKEN_CHANGEDBY>"
},
"System.CommentCount": "<INTEGER_COMMENT_COUNT>",
"System.Title": "<WORK_ITEM_TITLE>",
"System.BoardColumn": "New",
"System.BoardColumnDone": false,
"Microsoft.VSTS.Common.Priority": "<INTEGER_PRIORITY>",
"Microsoft.VSTS.Common.StateChangeDate": "<ISO_DATETIME_STATE_CHANGE>",
"Microsoft.VSTS.Common.ValueArea": "<VALUE_AREA>",
"Microsoft.VSTS.Common.BusinessValue": "<INTEGER_BUSINESS_VALUE>",
"Microsoft.VSTS.Scheduling.StoryPoints": "<NUMBER_STORY_POINTS>",
"Custom.Requester": {
"displayName": "<USER_DISPLAYNAME_REQUESTER>",
"url": "https://<IDENTITY_HOST>/<COLLECTION_GUID>/_apis/Identities/<GUID_REQUESTER>",
"_links": {
"avatar": {
"href": "https://<ADO_HOST>//_apis/GraphProfile/MemberAvatars/aad.<AAD_TOKEN_REQUESTER>"
}
},
"id": "<GUID_REQUESTER>",
"uniqueName": "<USER_UPN_REQUESTER>",
"imageUrl": "https://<ADO_HOST>//_apis/GraphProfile/MemberAvatars/aad.<AAD_TOKEN_REQUESTER>",
"descriptor": "aad.<AAD_TOKEN_REQUESTER>"
},
"Custom.IBPContactPerson": {
"displayName": "<USER_DISPLAYNAME_CONTACT>",
"url": "https://<IDENTITY_HOST>/<COLLECTION_GUID>/_apis/Identities/<GUID_CONTACT>",
"_links": {
"avatar": {
"href": "https://<ADO_HOST>//_apis/GraphProfile/MemberAvatars/aad.<AAD_TOKEN_CONTACT>"
}
},
"id": "<GUID_CONTACT>",
"uniqueName": "<USER_UPN_CONTACT>",
"imageUrl": "https://<ADO_HOST>//_apis/GraphProfile/MemberAvatars/aad.<AAD_TOKEN_CONTACT>",
"descriptor": "aad.<AAD_TOKEN_CONTACT>"
},
"Custom.DefinitionofReadyismet": true,
"Custom.Contributor1": {
"displayName": "<USER_DISPLAYNAME_CONTRIB1>",
"url": "https://<IDENTITY_HOST>/<COLLECTION_GUID>/_apis/Identities/<GUID_CONTRIB1>",
"_links": {
"avatar": {
"href": "https://<ADO_HOST>//_apis/GraphProfile/MemberAvatars/aad.<AAD_TOKEN_CONTRIB1>"
}
},
"id": "<GUID_CONTRIB1>",
"uniqueName": "<USER_UPN_CONTRIB1>",
"imageUrl": "https://<ADO_HOST>//apis/GraphProfile/MemberAvatars/aad.<AAD_TOKEN_CONTRIB1>",
"descriptor": "aad.<AAD_TOKEN_CONTRIB1>"
},
"WEF<GUID_KANBAN>Kanban.Column": "New",
"WEF<GUID_KANBAN>_Kanban.Column.Done": false,
"Custom.FinOpsCategory": "",
"Custom.FinOpsSubcategory": "",
"System.Description": "<MARKDOWN_DESCRIPTION_TEXT>",
"Microsoft.VSTS.Common.AcceptanceCriteria": "<MARKDOWN_ACCEPTANCE_CRITERIA_TEXT>",
"System.Tags": "<TAG_1>; <TAG_2>"
},
"multilineFieldsFormat": {
"System.Description": "markdown",
"Microsoft.VSTS.Common.AcceptanceCriteria": "markdown"
},
"_links": {
"self": {
"href": "https://<ADO_HOST>//<PROJECT_GUID>/_apis/wit/workItems/<WORK_ITEM_ID>"
},
"workItemUpdates": {
"href": "https://<ADO_HOST>//<PROJECT_GUID>/_apis/wit/workItems/<WORK_ITEM_ID>/updates"
},
"workItemRevisions": {
"href": "https://<ADO_HOST>//<PROJECT_GUID>/_apis/wit/workItems/<WORK_ITEM_ID>/revisions"
},
"workItemComments": {
"href": "https://<ADO_HOST>//<PROJECT_GUID>/_apis/wit/workItems/<WORK_ITEM_ID>/comments"
},
"html": {
"href": "https://<ADO_HOST>//<PROJECT_GUID>/_workitems/edit/<WORK_ITEM_ID>"
},
"workItemType": {
"href": "https://<ADO_HOST>//<PROJECT_GUID>/_apis/wit/workItemTypes/<WORK_ITEM_TYPE_URLENCODED>"
},
"fields": {
"href": "https://<ADO_HOST>//<PROJECT_GUID>/_apis/wit/fields"
}
},
"url": "https://<ADO_HOST>//<PROJECT_GUID>/_apis/wit/workItems/<WORK_ITEM_ID>"
}

[djm81]

OpenSpec Change Proposal

This issue is being addressed by OpenSpec change proposal: fix-ado-field-mapping-missing-fields

Change Location: specfact-cli-internal/openspec/changes/fix-ado-field-mapping-missing-fields/

Status: Proposed and validated

Key Changes:

• Fix missing Acceptance Criteria field mapping (Microsoft.VSTS.Common.AcceptanceCriteria)
• Fix missing Assignee display in preview output
• Add interactive template mapping command (specfact backlog map-fields)
• Update specfact init to copy templates to .specfact/templates/backlog/field_mappings/
• Extend documentation with step-by-step guides

Validation: ✅ Passed (no breaking changes detected)

See the change proposal for full details: openspec/changes/fix-ado-field-mapping-missing-fields/proposal.md