Which Artifact to Update When the Agent Gets Confused

You open a change folder to add a small feature. There are four artifact files. Proposal, specs, design, tasks. You do not know which one to update when the implementation reveals the design was wrong.

Most teams guess. They update the design but not the spec. Or they update the spec but not the tasks. The artifacts drift out of sync. The change archives with contradictions. Future readers cannot tell which artifact was authoritative.

The fix is knowing what each artifact is for, and updating the right one at the right moment.

The artifact flow

Artifacts build on each other in a natural progression.

Proposal, the why. Specs, the what changes. Design, the how. Tasks, the steps to take.

Each artifact provides context for the next one. The proposal tells you why the change matters. The specs describe what behavior changes. The design covers how you will build it. The tasks list the steps.

Here is the part teams miss. You can update any artifact at any time. If implementation reveals the design was wrong, update the design. Keep going. The artifact is a living document, not a contract signed at the start.

Proposal: the why and what

The proposal captures intent, scope, and approach at a high level. Three questions.

Why are we doing this. What is changing. How will we solve it.

A good proposal defines what is in scope and what is out of scope. A proposal to add dark mode might specify that the theme toggle and system preference detection are in scope, but custom color themes are out of scope. Saved for future work.

This prevents scope creep. The agent cannot inflate the change because the proposal says what is out of scope. The reviewer cannot argue scope because the proposal defines it.

Update the proposal when: scope changes, intent clarifies, or the approach fundamentally shifts. If the change is no longer about what the proposal says it is about, the proposal needs updating or the change needs splitting.

Specs: what is changing

Specs describe what is being added, modified, or removed relative to your current behavior. This is the most important artifact, because it is what merges into your source of truth when you archive.

Each spec contains requirements. Behaviors the system must have. And scenarios. Concrete examples in Given/When/Then format.

A requirement: "The system SHALL allow users to choose between light and dark themes."

A scenario: "GIVEN a user on any page, WHEN the user clicks the theme toggle, THEN the theme switches immediately."

Specs use RFC 2119 keywords. MUST is absolute requirement. SHOULD is recommended but exceptions exist. MAY is optional.

The keywords matter. They communicate requirement strength to the agent and to future readers. A MUST is non-negotiable. A SHOULD can be overridden with reason.

Update specs when behavior changes. Not when implementation changes. If the React Context versus Redux decision flips, that is a design change, not a spec change. If the session timeout changes from thirty minutes to fifteen, that is a spec change.

Design: the technical how

Design describes how you will build it. Architecture decisions. Data flow. File changes. Technology choices.

Good designs include the reasoning. Not just "use React Context". "Using React Context because the state is simple (binary light or dark), there are no complex transitions, and it avoids adding a Redux dependency."

The reasoning matters because future readers will question the choice. Without reasoning, they assume it was arbitrary and consider changing it. With reasoning, they can evaluate whether the reasoning still applies.

Update the design when: implementation reveals the approach will not work, a better solution is discovered, or dependencies change. The design is the most frequently updated artifact. That is normal. Implementation teaches you what the design got wrong.

Tasks: the implementation checklist

Tasks are the most hands-on artifact. A checklist of concrete steps. Grouped by topic. Hierarchical numbering (1.1, 1.2). Small enough to complete in one session.

As the agent implements each task, it checks it off. Progress is visible at a glance. If you pause and come back later, the tasks file shows exactly where you stopped.

Tasks should match the design. If the design says "create three components", the tasks should include creating each component. If the tasks drift from the design, the design is no longer authoritative.

Update tasks when: the work reveals more steps than expected, the order needs to change, or a step is no longer needed. Tasks are the most volatile artifact. That is fine. The point is to capture progress, not to predict perfectly.

The dependency graph

Artifacts form a dependency graph.

Proposal enables specs. You cannot spec a change you cannot describe.

Specs enable design. You cannot design how to build behavior you have not defined.

Design enables tasks. You cannot list steps for an approach you have not chosen.

Here is the key insight. Dependencies are enablers, not gates. They show what is possible to create, not what you must create next. You can skip design if you do not need it. You can create specs before or after design. The graph enables flexibility, not rigidity.

Keep specs lightweight

A common mistake is over-specifying.

Most changes should use lite specs. Short behavior-first requirements. Clear scope. A few acceptance checks.

Reserve full specs for higher-risk changes. Cross-team API modifications. Migrations. Security-sensitive changes. Anything where the cost of getting it wrong justifies the cost of detailed specification.

The goal is the lightest spec that still makes the change verifiable. If a lite spec covers it, do not write a full spec. If a full spec is needed, do not try to get away with lite.

The decision rule for updates

When implementation reveals something, ask which artifact the new information belongs to.

A new behavior. Update specs.

A different technical approach. Update design.

More steps than expected. Update tasks.

A scope change. Update proposal.

Most updates go to design or tasks. Few go to specs. Almost none go to the proposal once it is written. If you find yourself updating the proposal often, the proposal was premature, or the change is drifting from its original intent and should be split.