Early PreviewJoin us on the road to v1.0 — help shape the future of specification engineering.Get Involved →
SPECLAN mascotSPECLAN

Change Requests

Change Requests (CRs) are the formal mechanism for proposing modifications to SPECLAN specifications that have progressed beyond the early drafting stages. When a specification is in-development, under-test, or released status, direct editing is not allowed. Instead, you create a Change Request to propose and track the modification through its own approval lifecycle.

When Are Change Requests Required?

Change Requests are required when you need to modify a specification that is in one of these statuses:

Specification Status Direct Edit? Change Request Required?
draft Yes No
review Yes (limited) No
approved No Yes
in-development No Yes
under-test No Yes
released No Yes

Why not just edit directly? Locked specifications serve as the authoritative reference for development and testing. Direct edits would undermine traceability, break the audit trail, and risk introducing unreviewed changes into active work.

Change Request Types

SPECLAN supports five types of Change Requests, each suited to different situations:

Enhancement

Use when you want to add new capabilities or extend existing functionality to a specification.

Example: Adding a new acceptance criterion to an approved requirement, or expanding the scope of a feature.

Bugfix

Use when you need to correct an error in the specification itself -- not a code bug, but a specification that is incorrect or incomplete.

Example: Fixing a contradictory acceptance criterion, or correcting a wrong reference to another entity.

Breaking

Use when a change alters the existing behavior or contract defined by the specification. Breaking changes require careful review because they may affect downstream implementations and tests.

Example: Changing an API contract defined in a requirement, or modifying acceptance criteria in a way that invalidates existing tests.

Deprecation

Use when a specification or part of it should be phased out and eventually removed.

Example: Marking a feature as deprecated when it will be replaced by a newer approach.

Documentation

Use for non-functional changes to the specification text that do not alter the actual requirements -- such as fixing typos, improving clarity, or updating examples.

Example: Rewriting a confusing description, adding examples to acceptance criteria, or fixing formatting.

Change Request Lifecycle

Change Requests follow the same status lifecycle as other SPECLAN entities:

draft ──> review ──> approved ──> in-development ──> under-test ──> released ──> deprecated

How It Works

  1. Create (draft): A team member identifies a needed change and creates a CR linked to the parent specification (Feature or Requirement)
  2. Review: The CR is submitted for review, just like a regular specification
  3. Approve: Stakeholders review and approve the proposed change
  4. Implement (in-development): The development team implements the change
  5. Test (under-test): QA verifies the change meets the CR's acceptance criteria
  6. Release: The CR is marked as released, and the parent specification is updated accordingly
  7. Deprecate (optional): The CR can be deprecated if it is no longer relevant

Creating a Change Request

A Change Request includes:

---
id: CR-5282
title: "Add OAuth2 support to login requirement"
status: draft
parentId: R-4821
parentType: requirement
changeType: enhancement
---

Key fields:

  • parentId: The specification being modified (Feature or Requirement)
  • parentType: Whether the parent is a feature or requirement
  • changeType: One of enhancement, bugfix, breaking, deprecation, or documentation

Relationship to Parent Specifications

  • Each Change Request references exactly one parent specification
  • Multiple CRs can exist for the same parent (e.g., one enhancement and one bugfix)
  • When a CR is released, the parent specification is updated to reflect the change
  • The CR itself becomes part of the specification's history and audit trail

Common Workflows

Fixing a spec error during development

  1. Developer discovers an incorrect acceptance criterion in R-4821
  2. Developer creates CR-5282 (type: bugfix) referencing R-4821
  3. CR goes through review and approval
  4. The corrected criterion is applied to R-4821
  5. Development continues with the corrected specification

Adding scope to a released feature

  1. Product owner wants to add new capability to feature F-3012
  2. Creates CR-7901 (type: enhancement) referencing F-3012
  3. CR goes through full lifecycle: review, approval, development, testing
  4. When released, F-3012 is updated with the new scope
  5. Full audit trail shows when and why the change was made

Deprecating an old feature

  1. Team decides F-2001 will be replaced by F-3012
  2. Creates CR-8456 (type: deprecation) referencing F-2001
  3. After review and approval, F-2001 status transitions to deprecated
  4. The CR documents why the deprecation occurred

Tips for Working with Change Requests

  1. Choose the right type -- it affects how reviewers evaluate the change
  2. Link to the correct parent -- CRs must reference exactly one Feature or Requirement
  3. Write clear descriptions -- explain what needs to change and why
  4. Consider impact -- breaking changes require extra scrutiny
  5. Keep CRs focused -- one change per CR makes review and tracking easier

Related Topics