Backlog Generation

Backlog Generation

Overview

The backlog generation system produces structured development backlog items from design and build context. It analyzes the architecture, scope decisions, and deployment plan created during earlier stages, then decomposes them into epics, user stories, and tasks suitable for project tracking in GitHub Issues or Azure DevOps.

The backlog is scope-aware: items classified as in-scope during the design stage become stories, out-of-scope items are excluded, and deferred items are grouped into a separate epic for future consideration.

Command

az prototype generate backlog [options]

Parameter	Type	Default	Description
--provider	github or devops	None	Backlog provider. github creates GitHub Issues; devops creates Azure DevOps work items.
--org	string	None	Organization or owner name (GitHub org/user or Azure DevOps org).
--project	string	None	Project name (Azure DevOps project or GitHub repo).
--table	flag	false	Display backlog as a table instead of markdown.
--quick	flag	false	Skip the interactive session -- generate, confirm, and push in one pass.
--refresh	flag	false	Force fresh AI generation, bypassing cached items.
--status / -s	flag	false	Show current backlog state without starting a session.
--push	flag	false	In quick mode, auto-push items after generation.
--json / -j	flag	false	Output machine-readable JSON instead of formatted display.

Five Phases

The BacklogSession executes in five sequential phases:

Phase 1: Load Context

Loads design context (scope, architecture, services), build state (deployment plan, generated stages), deploy status, cost analysis, and any existing backlog state from .prototype/state/backlog.yaml. The enriched context is identical to what generate speckit uses — build stages with SKUs, deploy status per stage, cost analysis, and stage completion. If a previous session produced cached items and --refresh is not set, those items are reused.

Phase 2: Generate

When no cached items exist (or --refresh is specified), the project-manager agent performs structured decomposition of the enriched project context. The generation prompt includes four instruction sections:

1. Completed Work — analyzes Build Stages and Deploy Status tables. For stages where build status=generated or deploy status=deployed, creates items with status: "done" and done tasks, grouped under a "Completed POC Work" epic.

2. Production Readiness — creates a dedicated "Production Readiness" epic (separate from "Deferred / Future Work") with items for SKU upgrades, network hardening, CI/CD, monitoring, DR, and security. Knowledge-base production items are injected here.

3. Scope Boundaries — scope-aware generation (unchanged from before).

4. Provider-aware JSON schema — the output format varies by provider:

   • Azure DevOps: hierarchical JSON with children[] (User Stories under Features) and dict tasks
   • GitHub: flat items with dict tasks so completed work renders as [x]

Generation is scope-aware:

Scope Category	Treatment
in_scope	Converted to stories with full decomposition
out_of_scope	Excluded from generation entirely
deferred	Grouped into a separate "Deferred" epic

Production backlog items extracted from knowledge service files are injected into the Production Readiness epic.

Phase 3: Review and Refine

In interactive mode (the default), the session enters a conversational review loop. Users can inspect, modify, add, and remove items using slash commands or natural language.

Available slash commands:

Command	Action
/list	List all generated items
/show	Show details of a specific item
/add	Add a new item (uses PM agent to create a structured item via _enrich_new_item())
/remove	Remove an item
/preview	Preview the formatted output
/save	Save current state without pushing
/push	Push items to the configured provider
/status	Show session status
/help	Show available commands
/quit	Exit the session

The session also recognizes natural language: typing done, finish, accept, or lgtm completes the review.

Phase 4: Push

On /push (or automatically in --quick --push mode), items are created in the target provider:

• GitHub: Issues created via gh issue create with markdown bodies containing description, acceptance criteria, and task checklists using GitHub-flavored task list syntax (- [ ] for pending, - [x] for completed).
• Azure DevOps: Features, User Stories, and Tasks created via az boards work-item create with parent linking. The hierarchy is Feature → User Story → Task, matching the Azure DevOps work item types.

Before pushing, the session verifies authentication:

• GitHub: checks gh auth status
• Azure DevOps: checks az devops --help for extension availability

Phase 5: Report

Displays a summary with counts of items generated, items pushed, any failures, and URLs to the created work items.

Push Providers

GitHub Issues

Requires the GitHub CLI (gh) to be installed and authenticated. Each item becomes a GitHub issue with:

• A markdown body containing Description, Acceptance Criteria, and Tasks sections
• Task checklists using - [ ] syntax for trackable sub-tasks
• Hierarchical items include a Stories section with child items

Azure DevOps

Requires the Azure DevOps CLI extension (az devops). Items are created as a three-level hierarchy:

• Features for epics or parent items, via push_devops_feature()
• User Stories for individual stories (children of Features), via push_devops_story()
• Tasks for actionable sub-tasks (children of User Stories), via push_devops_task()
• Work items are linked to the specified organization and project using parent relations

Scope-Aware Generation

The backlog system respects scope decisions made during the design stage discovery conversation:

• In-scope items: Full decomposition into epics, stories, and tasks. These represent the core deliverables of the prototype.
• Out-of-scope items: Completely excluded from backlog generation. These were explicitly ruled out during discovery.
• Deferred items: Collected into a separate "Deferred / Future Work" epic. These are items acknowledged as valuable but intentionally postponed.

Task Format

Tasks support two formats for backward compatibility:

• String tasks (legacy): "Deploy stage 1" → rendered as - [ ] Deploy stage 1
• Dict tasks (new): {"title": "Deploy stage 1", "done": true} → rendered as - [x] Deploy stage 1

The dict format enables marking completed work with checked boxes in GitHub issues and checkbox markers in Azure DevOps descriptions.

Error Handling

The session includes QA-first error routing (see Error Analysis) and an escalation tracker for handling blockers during generation or push operations.

Examples

Generate a backlog interactively:

az prototype generate backlog

Generate and auto-push to GitHub:

az prototype generate backlog --provider github --org myorg --project myrepo --quick --push

Generate for Azure DevOps:

az prototype generate backlog --provider devops --org myorg --project myproject --quick --push

Check current backlog state:

az prototype generate backlog --status

Force regeneration and output as JSON:

az prototype generate backlog --refresh --json