Design Documents

Design documents in Release Cadence are generated from your requirements checkpoints. Each document is versioned, diffable, and can be pushed directly to Confluence or attached to a Jira Epic — keeping your Atlassian workspace in sync with what your team has agreed to build.

How Design Documents Work

A design document is always generated from a specific checkpoint — the immutable snapshot of your requirements at a point in time. This means the document is always traceable back to an agreed set of requirements, not the current (potentially in-progress) requirement list.

The generation process uses a system-provided template that structures your requirement data into a Markdown document ready to hand off to engineers, designers, or stakeholders. The template covers the feature description, project-level requirements, feature requirements grouped by MoSCoW priority, and acceptance criteria.

Generating a Design Document

1. Open a feature and navigate to the Design Documents tab.
2. Click Generate Document.
3. Select the checkpoint to generate from. The most recent checkpoint is selected by default.
4. Choose a generation mode (see below).
5. Click Generate. The document appears in the editor.

Generation Modes

Release Cadence offers three modes depending on where you are in the design cycle:

From Scratch

Generates a complete design document using the selected checkpoint as the sole input. Use this for the first design document on a feature, or when requirements have changed so substantially that starting fresh is cleaner than updating.

Full Document with Context

Generates a complete document using the selected checkpoint, but also provides the previous checkpoint as context. Useful when you want a full document that accounts for historical decisions without just focusing on what changed.

Incremental Changes

Instead of regenerating the full document, generates a focused update describing only what changed between two checkpoints. This is the most useful mode for ongoing design work — it produces a minimal, targeted prompt that describes additions, modifications, and removals since the last checkpoint.

You can use the incremental output directly as a prompt for an AI design assistant, or as structured notes for a human designer updating an existing document.

Viewing and Comparing Versions

Every time you generate a document from a checkpoint, Release Cadence stores a versioned copy. You can:

• View any version — Click any entry in the document history to see what was generated from that checkpoint.
• Compare versions — Select two versions to see a side-by-side diff with added, modified, and removed sections highlighted.
• Full document view — Shows the complete document with all changes highlighted inline.
• Changes-only view — Shows only the sections that changed. Useful for sharing targeted updates with stakeholders or feeding into AI tools.

Exporting and Sharing

Download as Markdown

Click Download on any design document version to save it as a .md file. This is useful for importing into any Markdown-compatible tool.

Push to Confluence

If you have the Atlassian integration configured, you can push a design document directly to Confluence:

1. Open the design document you want to push.
2. Click Push to Confluence.
3. Select the Confluence space and parent page (configured at the project level — see Admin Guide).
4. Choose whether to create a new page or update an existing one.
5. Click Push.

Once pushed, the Confluence page byline will show the checkpoint status — whether the document is up to date with the latest requirements or a newer checkpoint is available. See Atlassian Integration for details on the byline.

Attach to Jira Epic

You can also save a design document as an attachment on the linked Jira Epic. This keeps the design document visible directly in Jira without requiring a Confluence space.

1. Open the design document.
2. Click Attach to Jira.
3. Select the Jira Epic to attach to (or use the one already linked to this feature).
4. Click Attach. The document is uploaded as a Markdown file attachment on the Epic.

Best Practices

• Checkpoint per milestone, then diff to get your scope. When your team starts a new milestone or sprint, create a checkpoint that captures the requirements for that milestone. Use the diff between it and the previous checkpoint to produce a focused document covering only what's new — the features, acceptance criteria, and constraints that changed. This gives your team a clean, scoped brief for the work ahead, and since requirements are written from a user functionality perspective, the same diff makes an excellent foundation for release notes when the milestone ships.
• Use design documents as firm instructions for a coding agent. A generated document gives a coding agent precise, agreed-upon scope to work from. Must not and Should not requirements are especially valuable here — they set explicit boundaries that keep the agent from implementing out-of-scope behavior, choosing an unacceptable technical approach, or introducing functionality that was deliberately excluded from the milestone.
• Push early and update often. Pushing to Confluence early — even with an incomplete design — gets the document in front of stakeholders and makes updates visible through the byline status.