liveBook · Manning

Change proposal

As explained in Spec-Driven Development

A documented set of intended modifications to an existing software system, including their requirements and potential impacts.

A change proposal records what should change in a software system before implementation begins. It gives a coding agent durable intent to work from, rather than leaving scope and decisions in a conversation or asking the agent to infer them from code. section 2.4.4 section 2.4.5

Start with a bounded request and resolve scope through clarifying questions. For a URL shortener’s first slice, the decisions might be anonymous use, generated short paths, persistent mappings, and redirects—without accounts, custom aliases, expiration, or click tracking. The resulting change folder holds a proposal, design, specification, and task list. section 2.4.4

Each artifact answers a different implementation question:

  • The proposal states why the change matters, what changes, and which capabilities are in or out of scope. section 2.4.4
  • The design records context, goals, non-goals, and implementation decisions. section 2.4.4
  • The specification states requirements and observable scenarios, including invalid-input behavior. section 2.4.4
  • The task list turns those decisions into implementation work, such as validation, collision checks, and persistence. section 2.4.4
Listing 2.7 Excerpt from proposal.md
## Why
 
We need a minimal first slice that proves the core URL shortener loop: a user submits a long URL, receives a short URL on our domain, and later visits that short URL to reach the original destination. Keeping the scope narrow lets us validate the main product behavior without pulling in auth, analytics, custom aliases, or expiration.
 
## What Changes
 
- Add an anonymous URL shortening flow that accepts a long URL and returns a generated short URL on our domain.
- Add a redirect flow so visiting the generated short URL resolves to the original URL.
- Persist URL mappings so short links remain valid across process restarts.
- Validate submitted URLs and return clear errors for invalid input.
- Exclude account features, custom aliases, expiration, and click tracking from this slice.
 
## Capabilities
 
### New Capabilities
- `url-shortening`: create and resolve permanent, system-generated short URLs for anonymous users…
 

The first-slice proposal makes the core URL-shortening loop explicit while excluding features that would expand its scope. section 2.4.4

Changing an established rule

Suppose short URLs must now expire on day 90, including mappings already stored. Draft a fresh proposal against the existing specifications, then review its risks and impacts. The requirement may be marked modified, or represented as a deletion and addition, depending on how the original behavior was specified. Review the design and tasks before applying the change. section 2.4.6

After review, apply the proposal by working through its tasks, run the application, and test its behavior. Archive the implemented specifications so later proposals can use the recorded requirements and decisions. The operational advantage is not merely generated code: it is a reviewable account of intent that survives a new agent session and informs the next change. section 2.4.5 section 2.4.6

How Spec-Driven Development covers it

How deep it goes
Works through clarification, four proposal artifacts, review, application, verification, and archiving; does not detail every implementation task.
Examples
Uses a URL shortener’s initial creation-and-redirect flow and a later change imposing 90-day expiration on existing links.
What it assumes
Assumes an existing codebase for subsequent changes, while demonstrating how to specify a greenfield first slice.
What you can do after
Practice/perform a specification-first change by clarifying scope, reviewing proposal artifacts, applying tasks, verifying behavior, and archiving the result.
How it connects
Connects requirements and acceptance scenarios to design decisions, implementation tasks, specification-driven development, and change-impact review.

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Spec-Driven Development. The section links point to the parts of the book it draws on.