Record a Change

Record an eve snapshot after the product change is implemented and verified. A snapshot should describe the completed product result, not the step-by-step implementation log.

Recommended workflow

1. Complete the implementation.
2. Run the relevant verification.
3. Commit the implementation changes to Git.
4. Create an eve snapshot with the product meaning and verification.
5. Commit the generated .eve/ record to Git.

This repository follows that workflow for product changes.

For non-trivial agent work, start with a planned Snapshot: declare the Plan, wait for a locked revision, implement only after approval, then include the locked Plan ID and revision when completing the Snapshot.

Minimal record

Use a minimal record when the change is straightforward and the validation speaks for itself:

eve add \
  --title "Fix checkout toast timing" \
  --type bugfix \
  --summary "Checkout result toasts now appear after the checkout request finishes." \
  --validation "go test ./..."

eve commit

Planned record

When a Plan was approved before implementation, attach it to the Snapshot:

eve add \
  --title "Add checkout recovery" \
  --type feature \
  --summary "Users can retry a failed checkout from the same screen." \
  --validation "go test ./..." \
  --plan-id plan_123 \
  --plan-revision 1

eve commit

The Snapshot records whether changed paths, verification evidence, and policy matched the locked Plan.

Better record

Add user-visible behavior, decisions, risks, and artifacts when they clarify the work:

eve add \
  --title "Fix checkout toast timing" \
  --type bugfix \
  --summary "Checkout result toasts now appear after the checkout request finishes." \
  --user-visible-change "Users see an accurate success or failure toast after checkout." \
  --decision "Keep checkout feedback in the existing toast system." \
  --risk "Checkout failures could still be ambiguous without server details." \
  --validation "go test ./..." \
  --artifact "output/playwright/checkout-result-toast.png"

eve commit

Writing guidance

Use language that future maintainers can act on:

• Write summaries in product terms.
• Include exact verification commands.
• Describe artifacts so readers know what they prove.
• Add risks when something remains uncertain.
• Link related snapshots when a change corrects or supersedes earlier work.

Prefer "users can reset a password without losing the pending invitation" over "updated auth flow." The first version gives the next reader something concrete to verify.