Summary
Build content-aware Refresh generation paths — the self-aware incremental
mode (mode 1) from the AI-action-verbs design. Tier 2 work from
docs/development/design/ai-action-verbs-and-sharpen-mechanic.md
(Status: Proposed, 2026-06-21).
Why
Refresh is the mode that folds in an upstream change while preserving the user's
edits: prior draft plus the upstream delta, framed as "this is your draft; an
input changed; update it." It is conservative by design — it applies the delta
rather than re-deriving from scratch.
It is deliberately the exception, not the default. Per the design it exists
only where there are real user edits to protect and an upstream change to fold
in — few surfaces. The everyday "make it better" action is Sharpen (#92), not
Refresh.
Interaction with rollback (#93)
The design notes that once version history + rollback (#93) exists, the
data-safety rationale for Refresh evaporates (you can always restore a prior
revision). What remains is Refresh's edit-preservation value — folding an
upstream change into hand-edited content without discarding the edits. So this
issue should be scoped to the surfaces where edit preservation is the real need,
after #93 narrows the field.
Today's gap
The staleness banners on cover letter and prep are Refresh-intent but
Regenerate-behavior — they call from-scratch regeneration. They are the prime
candidates for a real Refresh path (and are also called out as Sharpen candidates;
which surface gets which is the open question below).
Scope
- A generation path that takes prior draft + upstream delta and applies the delta
while preserving user edits (never full re-derivation).
- Wire it into the surfaces where edit preservation genuinely matters.
Open question to resolve here
Acceptance criteria
Design: docs/development/design/ai-action-verbs-and-sharpen-mechanic.md
Related: #31 (Tier 1), #92 (Sharpen), #93 (rollback — narrows where Refresh is needed)
Summary
Build content-aware Refresh generation paths — the self-aware incremental
mode (mode 1) from the AI-action-verbs design. Tier 2 work from
docs/development/design/ai-action-verbs-and-sharpen-mechanic.md(Status: Proposed, 2026-06-21).
Why
Refresh is the mode that folds in an upstream change while preserving the user's
edits: prior draft plus the upstream delta, framed as "this is your draft; an
input changed; update it." It is conservative by design — it applies the delta
rather than re-deriving from scratch.
It is deliberately the exception, not the default. Per the design it exists
only where there are real user edits to protect and an upstream change to fold
in — few surfaces. The everyday "make it better" action is Sharpen (#92), not
Refresh.
Interaction with rollback (#93)
The design notes that once version history + rollback (#93) exists, the
data-safety rationale for Refresh evaporates (you can always restore a prior
revision). What remains is Refresh's edit-preservation value — folding an
upstream change into hand-edited content without discarding the edits. So this
issue should be scoped to the surfaces where edit preservation is the real need,
after #93 narrows the field.
Today's gap
The staleness banners on cover letter and prep are Refresh-intent but
Regenerate-behavior — they call from-scratch regeneration. They are the prime
candidates for a real Refresh path (and are also called out as Sharpen candidates;
which surface gets which is the open question below).
Scope
while preserving user edits (never full re-derivation).
Open question to resolve here
Acceptance criteria
the upstream delta.
from-scratch regeneration, with hand-edits demonstrably preserved.
Design:
docs/development/design/ai-action-verbs-and-sharpen-mechanic.mdRelated: #31 (Tier 1), #92 (Sharpen), #93 (rollback — narrows where Refresh is needed)