← Agent workflows guides

How to ask an agent to update the spec after discovering missing context

How-To Agent workflows Intermediate 1041013HOWTO-1041013

HOWTO-1041013Agent workflowsIntermediate

This guide shows you how to ask an agent to update a spec after implementation reveals missing context in a spec-driven development workflow.

Missing context is not a prompt failure by itself. It is a signal that a durable rule may be absent from the local contract. SpecDD gives you a clean way to turn that discovery into reviewed project context before code grows around a guess.

Short answer

Pause implementation, ask the agent to propose a spec update for the missing behavior or boundary, review the proposal, apply only the approved rule, then resume implementation from the updated spec.

When to use this guide

Use this guide when the agent discovers:

Steps

1. Stop implementation before guessing

If the agent reports missing context, do not approve a best-effort implementation.

Use:

List the missing Itinerary context.

Review whether the missing context is actually durable. If it only affects the current conversation, it may not belong in a spec. If it should guide future humans and agents, update the spec.

2. Identify the right spec to update

Update the nearest spec that owns the behavior.

For itinerary validation, that might be:

src/trips/itinerary.sdd

Do not put local behavior in a root spec just because the root spec is easy to find. Root specs should carry broad project intent and constraints. Local behavior belongs close to the files it governs.

3. Ask for a proposal, not direct implementation

Use:

Propose an Itinerary spec update for save-failure behavior.

The proposal should describe what section changes are needed and why. It should not immediately broaden code changes.

4. Review the proposal

Check whether the proposed update:

For example:

Must:
  Save failures return a validation result without storing a partial itinerary item.

Done when:
  Save-failure behavior is covered by a check.

Scenario: save failure
  Given itinerary storage fails
  When the person adds a valid itinerary item
  Then the operation reports a save failure
  And no partial itinerary item is stored

5. Apply the approved update

After review:

Update the Itinerary spec with the approved save-failure rule.

If the update creates a new task, keep task status accurate:

Tasks:
  [ ] Add save-failure handling.

Do not mark the task done as part of the spec update unless implementation and checks are already complete.

6. Resume implementation from the updated contract

Use:

Plan the save-failure handling change.

After plan review:

Implement the approved save-failure handling plan.

The implementation should now follow the updated spec instead of the original ambiguous prompt.

Best practices

Common mistakes

How to verify the result

The spec update workflow worked when:

← Agent workflows guides