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
