Update Spec-Driven Development design document

Wordpress

Workato

workitem

workplan

Workplan

Workplans

workstream

workstreams

worktree

## Summary

Spec-Driven Development (SDD) is fundamentally about capturing intent and using it to generate outputs through Agentic work. Today, context needed to execute work is scattered across issues, comments, design files, code, and people's heads. Agents that try to act on a work item without structured input produce inconsistent results because they lack the why, how, and what.

Spec-Driven Development (SDD) is about capturing intent and using it to drive agentic work. Today, the context needed to execute work is scattered across issues, comments, design files, code, and people's heads. Agents that act on a work item without structured input produce inconsistent results because they lack the why, how, and what.

SDD solves this by introducing a structured planning layer on GitLab work items. An **Agent plan** is collaboratively built by humans and AI agents, enriched with project context, and then consumed downstream by execution agents (Duo Developer) and validation agents (Duo Review).

**SDD supports human-led and autonomous work.** Our work supports Software Factory while serving a broader set of customer needs. Many customers need substantial human involvement, with people guiding decisions through execution. Software Factory focuses on autonomy, and the Workplan and its supporting features can serve that path too.

We are building this feature with the mindset that any work done should work for Agents and Human both. In practice what this means is that SDD is a way of working,

and we are seeing this rise in popularity with Agents. But the underlying concept is very human: documentation-centric way of developping, accelerated with Agents.

The readiness level signals readiness for execution. A future threshold could gate execution and help manage token costs. The decision log is designed to capture human and AI decisions from the work item through execution.

For product context see the [parent epic](https://gitlab.com/groups/gitlab-org/-/work_items/21218) and [wiki](https://gitlab.com/groups/gitlab-org/plan-stage/-/wikis/Spec-driven-development-(SDD)).

Throughout this design document:

- The **spec** is the work item description. It captures the Why (motivation) and the What (requirements).

- The **Workplan** is a separate artifact on the work item. It captures the How (implementation approach) and is consumed by downstream agents such as Duo Developer.

We build every part of this feature so it works for both agents and humans. SDD is a documentation-centric way of developing, accelerated by agents.

For product context, see the [parent epic](https://gitlab.com/groups/gitlab-org/-/work_items/22445), the [SDD wiki](https://gitlab.com/groups/gitlab-org/plan-stage/sdd/-/wikis/_Home) (GitLab team members only), and the [Workplan user documentation](https://docs.gitlab.com/user/work_items/workplan/).

### Terminology

| Term | Meaning |

| ---- | ------- |

| Spec | The work item description (Why and What). |

| Workplan | The plan artifact that captures the How. Written as one word. |

| Implementation widget | The parent widget on the work item that shows the Workplan status, the readiness level, and the actions to plan and implement. |

| `AgentPlan` | Legacy code name for the Workplan. It still appears in GraphQL types, the database, and backend classes. Aligning the backend naming is tracked in [issue 630474](https://gitlab.com/gitlab-org/gitlab/-/work_items/630474). |

| Readiness | Signals how ready a work item is for agent execution. The UI shows a readiness level of Low, Medium, or High. It is backed by a readiness score from 0 to 100, which the UI does not show. Formerly called confidence in the user interface; the rename is implemented in [merge request 259555](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/259555). |

## End-to-end flow

```mermaid

flowchart LR

    subgraph context["1 · Context Gathering"]

        Memory[Memory]

        DL[Decision log]

    subgraph intent["Intent"]

        Chat[Duo Chat] -->|creates| WI[Work item]

        Backlog[Existing work item] --> WI

    end

    subgraph generation["2 · Plan Generation"]

        IB[Interactive builder] -->|produces| WP[Agent plan widget]

        WP -->|evaluated by| Score[Readiness Score]

    subgraph planning["Refinement and planning"]

        Flow["Async workplan flow (workplan/v1)"]

        Questions[Clarifying questions in discussions]

        WP[Workplan]

        Score[Readiness]

        DL[Decision log]

    end

    subgraph validation["3 · Plan Validation"]

        DD[Duo Developer] -->|produces| MR[Merge Request]

        DR[Duo Review] -->|validates MR against plan| MR

    subgraph implementation["Implementation"]

        DD["Duo Developer (developer/v1)"] -->|opens| MR[Merge request]

    end

    WI[Work item] -->|user opens| IB

    Memory -->|injected into prompt| IB

    DL -->|fed as context| IB

    WP -->|read by| DD

    WP -->|read by| DR

    WI ---|Work item ↔ MR link| MR

    WI -->|user selects Plan| Flow

    Flow -->|pauses and asks| Questions

    Questions -->|user selects Continue with eligible replies| Flow

    Questions -.->|record and resolve decisions when available| DL

    Flow -->|writes| WP

    Flow -->|scores after writing the plan| Score

    WP -->|user selects Implement| DD

    MR -->|linked in Development section| WI

```

## Three layers to build

1. A user starts from an intent in Duo Chat, or opens an existing work item.

1. The user selects **Plan** on the work item. This turns on AI planning for the work item and starts the async workplan flow in the background. The user can leave the page while the flow runs.

1. The flow refines the work item and researches the project. When a decision is not the agent's to make, the flow posts a clarifying question in the work item discussions, pings the user, and pauses. If the description is too thin to research, it asks the user to expand the description instead.

1. A user answers and resolves question threads, or updates the description after a context request, then selects **Continue**. Question navigation uses thread resolution to track open questions. The resume service includes replies only from users with a project role above Guest; thread resolution is not required to resume. A context-request resume starts research again with the original goal.

1. The flow writes the Workplan, then computes readiness within the same flow when readiness scoring is available. Clarifying questions are recorded as open decisions, and resolving their threads through the work item UI resolves those decisions when the decision log is available. See [Human in the loop](human-in-the-loop.md#relationship-to-the-decision-log).

1. A user reviews the Workplan and selects **Implement**. Duo Developer uses the Workplan as its primary specification and opens a merge request. The merge request is linked in the work item's **Development** section.

## Workstreams

The architecture breaks down into three layers. Each layer has its own problems to solve and its own set of subpages with detailed designs.

The work is split into workstreams under the [parent epic](https://gitlab.com/groups/gitlab-org/-/work_items/22445). For timing and current status, see the epic and each workstream epic.

### 1. Context Gathering

| Workstream | Scope | Design |

| ---------- | ----- | ------ |

| [WS-2: Crafting the user journey of spec to code](https://gitlab.com/groups/gitlab-org/-/work_items/22703) | End-to-end user experience: entry points, opt-in AI planning, separation of spec and Workplan, fewer approval steps, execution visibility. | [Workplan](workplan.md) |

| [WS-3: Crafting the Workplan](https://gitlab.com/groups/gitlab-org/-/work_items/22702) | The async, agent-driven workplan generation flow: lifecycle, tool approvals, single-flow enforcement, concurrency, and observability. | [Async workplan flow](workplan-flow.md) |

| [WS-4: HITL and notifications](https://gitlab.com/groups/gitlab-org/-/work_items/22772) | Clarifying questions in work item discussions, answering them, notifications, and resuming the flow. | [Human in the loop](human-in-the-loop.md) |

| [WS-5: Decision log](https://gitlab.com/groups/gitlab-org/-/work_items/21552) | A record of decisions made about a work item, for humans and agents. | [Decision log](decision_log.md) |

| [WS-6: Work item readiness score](https://gitlab.com/groups/gitlab-org/-/work_items/23050) | A readiness level that signals whether a work item is ready for agent execution. | [Readiness](readiness.md) |

| [WS-7: Testing and feedback](https://gitlab.com/groups/gitlab-org/-/work_items/22773) | QA, bug triage and reporting, and dogfooding. | [Testing and feedback](#testing-and-feedback) |

Before a plan can be generated, the agent needs context: project conventions, past decisions, architectural patterns, related work items, and team preferences. The challenge is figuring out where to store these layers of context, how to keep them current, and how to inject the right slices at the right time.

The handoff to Duo Developer is described in [Downstream consumers](downstream_consumers.md).

| Component | Description | Subpage |

| ----------- | ------------- | --------- |

| Memory | Long-lived project and team context stored in git, with multiple layers (project, group, user) | [Memory and context injection](memory.md) |

| Decision log | Structured decisions (pending and resolved) captured on the work item, fed into plan generation sessions | [Decision log](decision_log.md) |

### Testing and feedback

### 2. Plan Generation

[WS-7](https://gitlab.com/groups/gitlab-org/-/work_items/22773) uses the [feedback issue](https://gitlab.com/gitlab-org/gitlab/-/work_items/630531) to turn dogfooding findings into work across the other workstreams. Current follow-ups include visibility of implementation progress, behavior on closed work items, and [usage metrics](https://gitlab.com/gitlab-org/gitlab/-/work_items/631308).

The Agent plan is the central artifact. Users talk with agents through the Interactive builder to iteratively shape a plan that captures the Why, How, What, and a clear list of pending questions and steps. Plans get refined over time and multiple stakeholders can contribute, so we need versioning, an auditing trail, and a lightweight review flow.

Measurement distinguishes reading a Workplan through the API from displaying a saved Workplan in the UI. Saving a plan no longer counts as a backend read ([merge request 257324](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/257324)), and a separate event tracks displaying the saved plan ([merge request 258352](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/258352)). Decision-log panel views and decision resolution also have dedicated events. See [Decision log](decision_log.md#observability).

| Component | Description | Subpage |

| ----------- | ------------- | --------- |

| Agent plan widget | Markdown-based work item widget that stores the plan | [Agent plan](work_plan.md) |

| Interactive builder | Reusable Duo Chat + live preview UI for iterating on LLM output | [Interactive builder](interactive_builder.md) |

| Plan readiness scoring | Lightweight quality gate that signals whether a plan is ready for agent execution | [Scoring](scoring.md) |

### Deferred designs

### 3. Plan Validation

These designs are not part of the current epic. They are kept for context.

Once a plan is approved, it needs to carry weight. Downstream agents read the plan, execute against it, and validate that the resulting merge request matches the stated intent. This requires a strong link between work items and MRs.

| Design | Status |

| ------ | ------ |

| [Downstream consumers](downstream_consumers.md) | The Duo Developer handoff is in scope. Duo Review validation and merge checks are deferred. |

| [Work item to merge request relationship](wi_mr_relationship.md) | Deferred. |

| Component | Description | Subpage |

| ----------- | ------------- | --------- |

| Work item ↔ MR relationship | First-class bidirectional link so downstream agents can find and validate against the plan | [Work item to MR relationship](wi_mr_relationship.md) |

| Downstream consumers | How Duo Developer and Duo Review read and use the plan | [Downstream consumers](downstream_consumers.md) |

## Constraints

- No live collaborative chat. Collaboration happens asynchronously through work item comments and threads.

- Workplans are available on issues and tasks.

- Only one workplan flow can run on a work item at a time.

- The backlog refinement loop, which estimates effort to find low-complexity issues in the first place, is out of scope.

## Decisions

| Date | Decision | Who |

| ------ | ---------- | ----- |

| 2026-03-30 | Short-lived artifact is an **Agent plan** on the work item (not standalone, supports all work item types). | Workshop |

| ---- | -------- | --- |

| 2026-03-30 | The short-lived artifact is a plan on the work item (not standalone, supports all work item types). | Workshop |

| 2026-03-31 | Output is **Markdown** through work item templates. | @fredericcaplette |

| 2026-03-31 | **Approval workflow out of scope** for current phase. | @izzychu, @shekharpatnaik |

| 2026-04-09 | Use **sync Duo Chat** for AI interactions on work items. | @vanessaotto, @fredericcaplette |

| 2026-04-09 | Use **sync Duo Chat** for AI interactions on work items. Superseded by the async workplan flow. | @vanessaotto, @fredericcaplette |

| 2026-04-09 | **Markdown over YAML** for human readability. | @fredericcaplette, @vanessaotto, @timzallmann |

## Constraints

- Agent sessions are single-user (async collaboration only through work item comments)

- Work item approvals do not exist on the platform

- MR-to-work-item link is the only bridge for Duo Review to access the plan

- IDE interactive builder out of scope for v1

- Long-lived Spec storage unresolved

## Timeline

| Workstream | Target | Confidence |

|------------|--------|------------|

| 0 - [Agent plan widget](https://gitlab.com/groups/gitlab-org/-/work_items/21511) | 2026-06-30 | Medium |

| 0.5 - [Plan scoring](https://gitlab.com/gitlab-org/gitlab/-/work_items/596916) | TBD | Not started |

| 1 - [MR enforcement](https://gitlab.com/groups/gitlab-org/-/work_items/21514) | TBD | Not started |

| 2 - [Memory loop](https://gitlab.com/groups/gitlab-org/-/work_items/21512) | TBD | Not started |

| 3 - [Decision log](https://gitlab.com/groups/gitlab-org/-/work_items/21552) | 2026-06-30 | Medium |

| [Interactive builder](https://gitlab.com/groups/gitlab-org/-/work_items/21653) | TBD | Medium |

Release stages: Core team (now) -> Internal preview (2026-05-30) -> Customer preview (TBD) -> GA (TBD).

| 2026-08-25 | The parent widget is named **Implementation** ([issue 612831](https://gitlab.com/gitlab-org/gitlab/-/work_items/612831#note_3734387905)). | @nickbrandt |

| 2026-09-08 | A paused workplan flow resumes through an explicit action, not automatically when a thread is resolved ([merge request 252945](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/252945)). | @stefanosxan |

| 2026-09-09 | The Implementation widget appears only after a user turns on AI planning for a work item ([issue 605174](https://gitlab.com/gitlab-org/gitlab/-/work_items/605174)). | WS-2 |

| 2026-09-09 | The decision log is independent of the Workplan and of AI planning ([issue 624791](https://gitlab.com/gitlab-org/gitlab/-/work_items/624791)). | WS-5 |

| 2026-09-15 | The decision log can be offered in the Free tier, but this is not a priority ([issue 628417](https://gitlab.com/gitlab-org/gitlab/-/work_items/628417)). | @gweaver, @nickbrandt |

| 2026-09-22 | The plan is named **Workplan**, written as one word ([issue 612831](https://gitlab.com/gitlab-org/gitlab/-/work_items/612831#note_3886070970)). | @nickbrandt, @brendan777 |

| 2026-09-23 | The **Implement** action runs Duo Developer asynchronously instead of opening Duo Chat ([issue 628801](https://gitlab.com/gitlab-org/gitlab/-/work_items/628801)). | WS-7 |

## Links

- [Parent Epic](https://gitlab.com/groups/gitlab-org/-/work_items/21218)

- [Wiki SSoT](https://gitlab.com/groups/gitlab-org/plan-stage/-/wikis/Spec-driven-development-(SDD))

- [Parent epic](https://gitlab.com/groups/gitlab-org/-/work_items/22445)

- [Previous parent epic](https://gitlab.com/groups/gitlab-org/-/work_items/21218)

- [SDD wiki](https://gitlab.com/groups/gitlab-org/plan-stage/sdd/-/wikis/_Home) (GitLab team members only)

- [SDD feature flags overview](https://gitlab.com/groups/gitlab-org/plan-stage/sdd/-/wikis/Feature-Flags): setup and rollout details (GitLab team members only).

- [Workplan user documentation](https://docs.gitlab.com/user/work_items/workplan/)

- [Prototype](https://plan-sdd-bdc021.gitlab.io/)

- [Latest walkthrough](https://gitlab.com/groups/gitlab-org/-/work_items/22703#note_3754968901)

- [Feedback issue for async refinement and workplan generation](https://gitlab.com/gitlab-org/gitlab/-/work_items/630531)

- [AI Panel architecture](../ai_panel/_index.md)

- [Design Issue](https://gitlab.com/gitlab-org/gitlab/-/work_items/592316)

- [Engineering Spike](https://gitlab.com/gitlab-org/gitlab/-/work_items/592314)

- [Duo Agent Platform memory design proposal](https://gitlab.com/gitlab-com/content-sites/handbook/-/merge_requests/20409). Memory and context injection are designed there instead of in SDD.

- [Workshop notes](https://docs.google.com/document/d/1zFs7ziXNBrY7rYvXhhWZvyavWT-j_DAqNwmxbMMTa4o/edit?tab=t.0)

---

title: "Decision log"

description: "Design for the Decision log work item widget that captures structured decisions for SDD context gathering."

description: "Design for the decision log, a record of the decisions made about a work item for humans and agents."

status: ongoing

maturity: still defining

creation-date: "2026-04-16"

## Summary

The Decision log is a new work item widget that captures structured decisions (pending and decided). It provides a reference point for humans and agents and is included as context whenever an Agent plan generation session starts.

The decision log is a record of the decisions made about a work item. It keeps the reason for each decision next to the work item, so the history is not lost in chat or in comment threads. Humans and agents both read it and write to it.

Epic: [Workstream 3 — Decision log](https://gitlab.com/groups/gitlab-org/-/work_items/21552)

When a complex work item needs a lot of alignment, pending questions get lost, and adding every resolved decision to the description makes it too long. Someone who joins later spends a long time catching up. With agents, collaboration moves faster, and humans and other agents need to see the decisions made in conversations between humans and agents.

For this iteration, the decision log is not a long-lived artifact. Its lifespan is tied to the work item.

Epic: [WS-5: Decision log](https://gitlab.com/groups/gitlab-org/-/work_items/21552)

User documentation: [Decision log](https://docs.gitlab.com/user/work_items/workplan/#decision-log)

## Scope

- Available on issues and tasks, and on custom work item types based on them.

- A work item does not need a Workplan or AI planning to have a decision log.

- Viewing and recording decisions is available to the Planner, Reporter, Security Manager, Developer, Maintainer, and Owner roles. A stricter permission model is still being discussed.

- The decision log opens in a side panel from the work item header. The header button counts resolved, non-archived decisions. Open decisions are stored but hidden from the panel for this iteration ([issue 631883](https://gitlab.com/gitlab-org/gitlab/-/work_items/631883)).

## Data model

A list of decision entries on the work item. Each entry has: description, status (pending/decided), author, date, and optionally an assignee. Storage format TBD — options are a JSON column on a widget table or individual records in a dedicated table. Most likely the issue table is too big and we'd want a separate table.

Decisions are stored in their own tables, `work_item_decisions` and `work_item_decision_options`, joined to the work item. The backend work is tracked in the [data model and backend epic](https://gitlab.com/groups/gitlab-org/-/work_items/22374).

The existing model derives a decision's state from its timestamps:

- `active`: An open decision, with no resolution or archive timestamp.

- `resolved`: A decision with a resolution timestamp and no archive timestamp.

- `archived`: A decision with an archive timestamp.

This lifecycle supports creating an open question with options and resolving it later. A decision can also be created already resolved to record an outcome directly.

The API and model use `question` for the question a decision answers. Create and update mutations accept it alongside the legacy `title` argument during the transition ([merge request 259900](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/259900)). The database column rename is a separate follow-up.

## Interactions

- Humans can add pending decisions manually.

- Agents can read the log as input context and write new entries through work item tools in AI Gateway.

- Resolving a comment thread with "Make a decision" stores the result in the log, bridging the Notes system with the Decision log widget.

- Assigning a pending decision to a user creates a to-do item through the existing to-do system.

- Raise any pending threads within the widget so that you can make decisions from the widget per thread and leave no threads unanswered.

First iteration, tracked in the [frontend epic](https://gitlab.com/groups/gitlab-org/-/work_items/22375):

- Record a decision manually. Required fields are the decision, who decided, and the context. Optional fields are the reasoning and a source link.

- Show each decision as a card with the decision, the open question it answers, who settled it and when, where it came from, and the context and reasoning.

- Link a decision to the thread and comment that produced it.

- Edit the decision text and decider, delete a decision, or archive it. Archived decisions can be shown with a visibility toggle.

- Resolving a Duo question through the work item UI resolves its matching decision. A general action to resolve any thread by creating or picking a decision is still tracked in [issue 603073](https://gitlab.com/gitlab-org/gitlab/-/work_items/603073).

- Recording or resolving a decision creates an activity-feed system note linking directly to its card. The note follows the decision log's visibility rules ([merge request 259191](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/259191)).

Deferred to a later iteration:

- An approval lifecycle beyond the existing active, resolved, and archived states, including negative decisions.

- Decision assignees and the to-do items they create.

- Cascading decisions from child work items up to the root epic.

- Decision categories, ordering, and superseding a decision.

## Agents

- The backend creates an open decision when the workplan flow's service account posts a valid clarifying question. It stores the question, options, discussion, and workflow reference.

- The frontend resolves the matching decision when the user resolves the question thread through the work item UI. This requires the decision log to be available on the work item. See [Human in the loop](human-in-the-loop.md#relationship-to-the-decision-log) for failure handling and older questions.

## Observability

Internal events track a decision being recorded as already resolved, an open decision being resolved, and the decision-log panel being opened. Resolution events include how the decision was settled. Creating an open question alone is not counted as a resolved decision ([merge request 261013](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/261013)).

## Decisions

| Date | Decision | Who |

| ---- | -------- | --- |

| 2026-09-09 | The decision log is independent of the Workplan and of AI planning. Its rendering is split from the AI planning widget ([issue 624791](https://gitlab.com/gitlab-org/gitlab/-/work_items/624791)). | WS-5 |

| 2026-09-15 | The decision log can be offered in the Free tier, but this is not a priority ([issue 628417](https://gitlab.com/gitlab-org/gitlab/-/work_items/628417)). Until then, it stays behind the `ai_workflows` licensed feature. | @gweaver, @nickbrandt |

## Consumption

## Open questions

Whenever a Duo Chat session starts on a work item, the Decision log is read through the work item tool.

- How to expose open decisions and their options in the panel ([issue 631615](https://gitlab.com/gitlab-org/gitlab/-/work_items/631615)).

- Whether reopening a resolved decision should modify it in place or supersede it ([issue 632762](https://gitlab.com/gitlab-org/gitlab/-/work_items/632762)).

- Requiring both work-item update permission and internal-note access, including behavior on archived projects ([issue 632270](https://gitlab.com/gitlab-org/gitlab/-/work_items/632270)).