You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The current backlog sync and refinement implementation doesn't properly handle the structural differences between GitHub issues (single body with markdown headings) and Azure DevOps work items (separate fields like Description, Acceptance Criteria, Story Points, Priority, Business Value). This causes incorrect field assignment, validation failures for ADO items, missing story points/business value/priority calculations, and inability to support custom ADO template field mappings. Without proper field mapping, teams cannot effectively refine backlog items, calculate complexity scores, detect stories that need splitting, or adapt to custom ADO templates.
What Changes
NEW: Implement abstract field mapping layer (FieldMapper abstract base class) that defines canonical field names (description, acceptance_criteria, story_points, business_value, priority, value_points, work_item_type) and provides provider-specific mappers (GitHub, ADO, Jira, Linear) with full Kanban/Scrum/SAFe framework alignment.
NEW: Add GitHubFieldMapper that extracts fields from markdown body using heading patterns (e.g., ## Acceptance Criteria, ## Story Points).
NEW: Add AdoFieldMapper that extracts fields from separate ADO fields (System.Description, System.AcceptanceCriteria, Microsoft.VSTS.Common.StoryPoints, etc.) with custom template mapping support.
NEW: Add template configuration schema for custom ADO field mappings with YAML configuration support.
NEW: Add default ADO field mapping templates (ado_default.yaml, ado_scrum.yaml, ado_agile.yaml, ado_safe.yaml, ado_kanban.yaml) with fallback to custom mappings.
EXTEND: Add story_points, business_value, priority, value_points (SAFe), acceptance_criteria, and work_item_type fields to BacklogItem model for full agile framework support (Kanban, Scrum, SAFe).
EXTEND: Update converters to use field mappers instead of direct field access.
EXTEND: Update refinement validation to be provider-aware (GitHub: check markdown headings in body, ADO: check separate fields).
EXTEND: Add story splitting detection logic that flags stories > 13 points (Scrum) or multi-sprint stories for splitting into multiple stories under the same feature, with SAFe-specific validation (Feature → Story hierarchy, Value Points calculation).
EXTEND: Include story points, business value, and priority in refinement prompts and validation scoring.
EXTEND: Add --custom-field-mapping option to specfact backlog refine command for specifying custom ADO field mapping file.
EXTEND: Add story splitting suggestions to specfact backlog refine command output when complex stories are detected.
Acceptance Criteria
ADO work items correctly extract Description, Acceptance Criteria, Story Points, Business Value, Priority, Value Points, and Work Item Type
GitHub issues correctly extract all fields from markdown body
Refinement validation works correctly for both GitHub and ADO (provider-aware)
Story points, business value, priority are used for refinement scoring
Story splitting detection works (stories > 13 points flagged for splitting)
Custom ADO field mappings are supported via YAML configuration
Full Kanban/Scrum/SAFe framework alignment (work item types, hierarchies, Value Points, WSJF)
Why
The current backlog sync and refinement implementation doesn't properly handle the structural differences between GitHub issues (single body with markdown headings) and Azure DevOps work items (separate fields like Description, Acceptance Criteria, Story Points, Priority, Business Value). This causes incorrect field assignment, validation failures for ADO items, missing story points/business value/priority calculations, and inability to support custom ADO template field mappings. Without proper field mapping, teams cannot effectively refine backlog items, calculate complexity scores, detect stories that need splitting, or adapt to custom ADO templates.
What Changes
FieldMapperabstract base class) that defines canonical field names (description, acceptance_criteria, story_points, business_value, priority, value_points, work_item_type) and provides provider-specific mappers (GitHub, ADO, Jira, Linear) with full Kanban/Scrum/SAFe framework alignment.GitHubFieldMapperthat extracts fields from markdown body using heading patterns (e.g.,## Acceptance Criteria,## Story Points).AdoFieldMapperthat extracts fields from separate ADO fields (System.Description,System.AcceptanceCriteria,Microsoft.VSTS.Common.StoryPoints, etc.) with custom template mapping support.story_points,business_value,priority,value_points(SAFe),acceptance_criteria, andwork_item_typefields toBacklogItemmodel for full agile framework support (Kanban, Scrum, SAFe).--custom-field-mappingoption tospecfact backlog refinecommand for specifying custom ADO field mapping file.specfact backlog refinecommand output when complex stories are detected.Acceptance Criteria
OpenSpec Change Proposal:
improve-backlog-field-mapping-and-refinement