Which Artifact to Update When the Agent Gets Confused

You open a change folder and find four artifact files: proposal, specs, design, tasks. The work shows the design was wrong, and you do not know which file to update. Most teams guess, the artifacts drift out of sync, and the change archives with contradictions no future reader can untangle.

The artifact flow

Proposal is the why. Specs are the what changes. Design is the how. Tasks are the steps. Each feeds the next, and the part teams miss: you can update any artifact at any time. If the work shows the design was wrong, update the design and keep going. Artifacts are living documents, not contracts signed at the start.

Proposal and specs

The proposal captures intent, scope, and approach, including what is explicitly out of scope; that is what stops scope creep, because the agent cannot inflate what the proposal excludes. Update it when scope or core intent shifts. Specs describe behavior changes: requirements the system must have, and scenarios in Given/When/Then. They use RFC 2119 keywords: MUST is absolute, SHOULD allows exceptions, MAY is optional. Update specs when behavior changes, not implementation.

Design and tasks

Design records how you will build it, with reasoning, not just "use React Context" but why, because future readers without reasoning assume the choice was random. It is the most frequently updated artifact; implementation teaches you what the design got wrong. Tasks are the numbered checklist the agent works through and checks off, showing exactly where you stopped. Tasks change the most, and that is fine: they capture progress, not prophecy.

Dependencies are enablers, not gates

Proposal enables specs (you cannot spec what you cannot describe), specs enable design, design enables tasks. But the graph shows what is possible, not what you must do next: you can skip design when you do not need it. Flexibility, not rigidity.

The decision rule

When the work reveals something new, route it: a new behavior updates specs; a different technical approach updates design; more steps than expected update tasks; a scope change updates the proposal. Most updates land in design and tasks, few in specs, almost none in the proposal. Constant proposal edits mean the proposal was premature or the change is drifting and should be split. And keep specs lightweight: lite specs for most changes, full specs only for high-risk work like cross-team APIs, migrations, and security surfaces.

The smallest test

Open your current change folder and check the last edit landed in the right artifact. If the design changed but you edited tasks, move it.