|
| 1 | +# Backlog Add (Interactive Issue Creation) |
| 2 | + |
| 3 | +## ADDED Requirements |
| 4 | + |
| 5 | +### Requirement: Backlog adapter create method |
| 6 | + |
| 7 | +The system SHALL extend backlog adapters with a create method that accepts a unified payload and returns the created item (id, key, url). |
| 8 | + |
| 9 | +**Rationale**: Creation is currently out-of-band (user creates in GitHub/ADO UI). CLI-driven creation with consistent payload shape allows draft → validate → create flow. |
| 10 | + |
| 11 | +#### Scenario: Create issue via GitHub adapter |
| 12 | + |
| 13 | +**Given**: A GitHub adapter is configured and project_id (owner/repo) is set |
| 14 | + |
| 15 | +**When**: The user or add command calls `create_issue(project_id, payload)` with payload containing type, title, description, and optional parent_id |
| 16 | + |
| 17 | +**Then**: The adapter maps the unified payload to GitHub Issues API (e.g. POST /repos/{owner}/{repo}/issues) and creates the issue |
| 18 | + |
| 19 | +**And**: The method returns a dict with id, key (or number), and url of the created issue |
| 20 | + |
| 21 | +**Acceptance Criteria**: |
| 22 | + |
| 23 | +- Payload is provider-agnostic (type, title, description, parent_id, optional fields) |
| 24 | +- Adapter performs provider-specific mapping (e.g. GitHub labels for type, body for description) |
| 25 | +- Failure (auth, validation) is reported; no silent swallow |
| 26 | + |
| 27 | +#### Scenario: Create work item via ADO adapter |
| 28 | + |
| 29 | +**Given**: An ADO adapter is configured and project_id is set |
| 30 | + |
| 31 | +**When**: The user or add command calls `create_issue(project_id, payload)` with payload containing type, title, description, and optional parent_id |
| 32 | + |
| 33 | +**Then**: The adapter maps the unified payload to ADO Create Work Item API and creates the work item |
| 34 | + |
| 35 | +**And**: The method returns a dict with id, key, and url of the created work item |
| 36 | + |
| 37 | +**Acceptance Criteria**: |
| 38 | + |
| 39 | +- ADO work item type is derived from unified type via template type_mapping |
| 40 | +- Parent link is created when parent_id is present and adapter supports it |
| 41 | + |
| 42 | +### Requirement: Backlog add command |
| 43 | + |
| 44 | +The system SHALL provide a `specfact backlog add` command that supports interactive creation of backlog issues with type selection, optional parent, title/body, validation (parent exists, allowed type, optional DoR), and create via adapter. |
| 45 | + |
| 46 | +**Rationale**: Teams need a single flow to add well-scoped, hierarchy-aligned issues from CLI or slash prompt. |
| 47 | + |
| 48 | +#### Scenario: Add story with parent |
| 49 | + |
| 50 | +**Given**: A backlog graph or project is loaded (e.g. from fetch_all_issues and fetch_relationships or existing graph) |
| 51 | + |
| 52 | +**And**: Template or backlog_config defines allowed types and creation hierarchy (e.g. Story may have parent Feature or Epic) |
| 53 | + |
| 54 | +**When**: The user runs `specfact backlog add --type story --parent FEAT-123 --title "Implement X" --body "As a user..."` (or equivalent interactive prompts) |
| 55 | + |
| 56 | +**Then**: The system validates that parent FEAT-123 exists in the graph and that Story is allowed under that parent type |
| 57 | + |
| 58 | +**And**: If validation passes, the system builds a unified payload and calls the adapter's create_issue(project_id, payload) |
| 59 | + |
| 60 | +**And**: The CLI outputs the created issue id, key, and url |
| 61 | + |
| 62 | +**Acceptance Criteria**: |
| 63 | + |
| 64 | +- Validation fails clearly when parent does not exist or type is not allowed |
| 65 | +- Optional --check-dor runs DoR rules (from backlog-refinement / .specfact/dor.yaml) on the draft and warns or fails when not met |
| 66 | + |
| 67 | +#### Scenario: Add issue with custom hierarchy |
| 68 | + |
| 69 | +**Given**: backlog_config (or template) defines creation_hierarchy with custom allowed parent types per child type (e.g. Spike may have parent Epic or Feature) |
| 70 | + |
| 71 | +**When**: The user runs `specfact backlog add --type spike --parent EPIC-1 --title "Spike: evaluate Y"` |
| 72 | + |
| 73 | +**Then**: The system loads creation hierarchy from config and validates that Spike is allowed under Epic |
| 74 | + |
| 75 | +**And**: If allowed, the system creates the issue and optionally links parent |
| 76 | + |
| 77 | +**Acceptance Criteria**: |
| 78 | + |
| 79 | +- Hierarchy rules are read from template or backlog_config; no hardcoded hierarchy |
| 80 | +- Multiple levels (epic, feature, story, task, bug, spike, custom) are supported |
| 81 | + |
| 82 | +#### Scenario: Non-interactive (scripted) add |
| 83 | + |
| 84 | +**Given**: All required options are provided on the command line (e.g. --type, --title, --non-interactive) |
| 85 | + |
| 86 | +**When**: The user runs `specfact backlog add --type story --title "T" --body "B" --non-interactive` |
| 87 | + |
| 88 | +**Then**: The system does not prompt for missing fields; it uses provided values or fails with clear error for missing required fields |
| 89 | + |
| 90 | +**And**: Validation (parent if provided, DoR if --check-dor) runs before create |
| 91 | + |
| 92 | +**Acceptance Criteria**: |
| 93 | + |
| 94 | +- Required fields are documented (e.g. type, title; body may be optional per provider) |
| 95 | +- Missing required fields in non-interactive mode result in clear error exit |
| 96 | + |
| 97 | +### Requirement: Creation hierarchy configuration |
| 98 | + |
| 99 | +The system SHALL support configurable creation hierarchy (allowed parent types per child type) via template or backlog_config so that Scrum, SAFe, Kanban, and custom hierarchies work without code changes. |
| 100 | + |
| 101 | +**Rationale**: Different frameworks and orgs use different trees (e.g. Story under Feature vs Story under Epic); configuration avoids hardcoding. |
| 102 | + |
| 103 | +#### Scenario: Default hierarchy from template |
| 104 | + |
| 105 | +**Given**: A template (e.g. ado_scrum) is selected and does not define creation_hierarchy |
| 106 | + |
| 107 | +**When**: The add command needs to validate parent type for a new item |
| 108 | + |
| 109 | +**Then**: The system derives allowed parent types from existing type_mapping and dependency_rules (e.g. PARENT_CHILD) where possible |
| 110 | + |
| 111 | +**And**: If derivation is not possible, a conservative default (e.g. any type or no parent) is used and documented |
| 112 | + |
| 113 | +#### Scenario: Custom hierarchy in backlog_config |
| 114 | + |
| 115 | +**Given**: ProjectBundle.metadata.backlog_config (or .specfact/spec.yaml backlog section) contains creation_hierarchy with entries such as story: [feature, epic], task: [story] |
| 116 | + |
| 117 | +**When**: The user adds an item with --type story --parent FEAT-1 |
| 118 | + |
| 119 | +**Then**: The system validates that "feature" is in the allowed parent types for "story" and that FEAT-1 exists and has type Feature |
| 120 | + |
| 121 | +**And**: Validation fails clearly if parent type is not allowed |
| 122 | + |
| 123 | +**Acceptance Criteria**: |
| 124 | + |
| 125 | +- creation_hierarchy is optional; when absent, default or derived rules apply |
| 126 | +- Validation uses both existence of parent in graph and allowed type from hierarchy |
0 commit comments