# 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](Home.md) 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](https://cli.github.com/) (`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](Error-Analysis.md)) and an [escalation tracker](Escalation.md) for handling blockers during generation or push operations.

## Examples

Generate a backlog interactively:

```bash
az prototype generate backlog
```

Generate and auto-push to GitHub:

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

Generate for Azure DevOps:

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

Check current backlog state:

```bash
az prototype generate backlog --status
```

Force regeneration and output as JSON:

```bash
az prototype generate backlog --refresh --json
```