Checkpoints

A checkpoint is an immutable snapshot of your requirements at a point in time. Once created, it can never be edited — which makes it the reliable foundation for generating design documents and tracking what changed between design cycles.

Why Checkpoints Exist

Requirements change. Customers give feedback, priorities shift, and scope gets refined. Without a way to lock requirements at a moment in time, it's impossible to answer questions like: "What did we agree to build?", "What changed since the last design review?", or "Why does the current design document differ from what engineering is implementing?"

Checkpoints solve this by creating a permanent, versioned record of requirements your team signed off on. Each checkpoint feeds directly into design document generation — the design doc is always generated from a specific checkpoint, not from the current (potentially in-flux) requirement list.

What Gets Included in a Checkpoint

A checkpoint captures all requirements with a status of Ready for Checkpoint at the moment it is created:

• All project-level requirements (from Project Settings → Project Requirements) that are Ready for Checkpoint
• All feature-level requirements for the feature that are Ready for Checkpoint
• For each requirement: title, description, priority, type, and all acceptance criteria

Requirements still in Draft status are not included. This is intentional — a Draft requirement hasn't been reviewed yet and shouldn't lock into an immutable record.

When to Create a Checkpoint

Create a checkpoint when your team has agreed on a set of requirements and is ready to move into design or implementation. Common triggers:

• Before starting design work — Lock the requirements so the designer is working from an agreed baseline.
• After a stakeholder review — Capture the approved set of requirements from the review session.
• Before a sprint begins — Ensure engineers have a stable specification to build against.
• After significant feedback — When survey results have changed requirements meaningfully, checkpoint the new agreed state before regenerating design documents.

Creating a Checkpoint

1. Open the feature you want to checkpoint.
2. Navigate to the Requirements tab.
3. Confirm all requirements you want included are in Ready for Checkpoint status. Update any that are still in Draft.
4. Click Create Checkpoint.
5. Add an optional label or note to describe what this checkpoint represents (e.g., "Post-beta survey review" or "Sprint 4 baseline").
6. Confirm. The checkpoint is created immediately and cannot be modified.

Checkpoint States

After a checkpoint is created, your feature's requirements context shows one of these states:

• Up to date — The most recent checkpoint matches the current set of Ready requirements. No requirements have been added, edited, or removed since the last checkpoint.
• Changes pending — Requirements have been added or modified since the last checkpoint. A new checkpoint is needed before generating an updated design document.
• No checkpoint yet — No checkpoint has been created for this feature. Requirements exist but have never been locked.

These same states are surfaced in the Confluence byline when you push a design document — letting anyone viewing the Confluence page see whether the design reflects the latest agreed requirements.

Viewing Checkpoint History

Every checkpoint is stored permanently. To view the history:

1. Open the feature and go to the Requirements tab.
2. Click View Checkpoint History.
3. Each checkpoint is listed with its creation date, label, and how many requirements it contains.
4. Click any checkpoint to see the full list of requirements it captured.

Comparing Two Checkpoints

The diff view lets you compare any two checkpoints side by side to see exactly what changed. This is useful for understanding scope changes between design cycles and for generating targeted design document updates.

1. In the checkpoint history, select Compare on any checkpoint.
2. Choose a second checkpoint to compare against (typically the previous one).
3. The diff view highlights requirements that were added, modified, or removed between the two checkpoints.

This diff is also used when generating a design document in incremental changes mode — the document focuses only on what changed between checkpoints rather than regenerating the entire spec. See Design Documents for details.

Best Practices

• Checkpoint before design, not after. A checkpoint that happens after design work is retroactive documentation, not a useful baseline.
• Don't wait for perfection. Requirements will always evolve. A checkpoint with minor gaps is more useful than no checkpoint at all — you can always create a new one when requirements are updated.
• Use descriptive labels. A label like "Initial scope — no authentication" is far more useful six months later than "Checkpoint 3."
• Checkpoint after major feedback cycles. If you've just analyzed a round of survey results and updated requirements, create a new checkpoint to capture the current agreed state.