Summary
Add a draft/review step to the decomposition phase so users can see and approve the proposed items before they are created in Jira. This applies to all split levels: epics→story and epic→tasks.
Motivation
Today, when Forge decomposes a ticket into child items (epics from a story, tasks from an epic), those items are created directly in Jira. If the decomposition is off — wrong scope, missing items, unnecessary items — the user has to clean up after the fact. A draft review step would let users inspect, revise, and approve the breakdown before anything is created, reducing rework and giving more confidence in the output.
Proposed Behavior
- Forge generates the decomposition as usual
- Instead of immediately creating Jira tickets, Forge presents a draft of the proposed items for review — accessible from the parent entity (e.g. all proposed epics visible from the story, all proposed tasks visible from the epic)
- The user reviews, requests changes, or approves
- On approval, Forge creates the child items in Jira
Open Questions
Where should the draft be presented?
This is the key design decision. Some options to consider:
- Jira comment — consistent with existing approval flow; no new tooling; can get long/noisy for many items; limited formatting
- GitHub PR (in proposals repo) — rich markdown rendering; inline comments for feedback; consistent with PRD/spec PR flow; requires proposals repo setup; another PR to manage
- Dedicated UI / dashboard — best UX for reviewing structured item lists; requires building new UI surface
- Jira epic/ticket description — items listed in parent ticket; easy to find; clutters the ticket; awkward for revision flow
Where should the draft file be stored?
When the draft is document-based, where does the file live?
- Jira attachment on the parent ticket
- GitHub (link posted to Jira) — requires handling commits earlier than currently planned
- Hybrid: start as a Jira attachment, move to GitHub after approval for better auditing
- Other?
Other open questions
- Should the draft support partial approval (approve some items, revise others)?
- Should the user be able to reorder, add, or remove items in the draft?
- How should revision requests work — same
! prefix comment syntax as other stages?
- Should
forge:yolo skip this gate (consistent with other approval gates)?
Summary
Add a draft/review step to the decomposition phase so users can see and approve the proposed items before they are created in Jira. This applies to all split levels: epics→story and epic→tasks.
Motivation
Today, when Forge decomposes a ticket into child items (epics from a story, tasks from an epic), those items are created directly in Jira. If the decomposition is off — wrong scope, missing items, unnecessary items — the user has to clean up after the fact. A draft review step would let users inspect, revise, and approve the breakdown before anything is created, reducing rework and giving more confidence in the output.
Proposed Behavior
Open Questions
Where should the draft be presented?
This is the key design decision. Some options to consider:
Where should the draft file be stored?
When the draft is document-based, where does the file live?
Other open questions
!prefix comment syntax as other stages?forge:yoloskip this gate (consistent with other approval gates)?