edit-process-carefully

name	edit-process-carefully
description	How to edit an important document carefully — small steps, prioritise by ease × value, show before/after, get approval, keep changes surgical, and signpost rather than duplicate.
last_updated	"2026-06-25T00:00:00.000Z"
tools_required	[]
dependencies	[]
agent_type	main_agent

Edit an important document carefully

Use this when editing any important document — one whose exact wording is load-bearing, that has many readers, or that is costly to get wrong (process docs, instructions, policies, specs). The aim is twofold: make the document as good as it can be, and keep it easy to improve later.

See also

• signposting-to-single-source-of-truth — prefer linking to a single source of truth over duplicating content
• write-help-evergreen-doc — writing/maintaining an individual doc
• documentation-update — keeping a set of docs current

In general

• Prioritise by a combination of ease and value. When handed many ideas at once, first group related ones together, prioritise the groups by ease × value, then work through them in that order — rather than tackling them in the order given.
• Tackle just one or two related changes at a time, then get approval before moving onto the next set.

Chat responses

• Keep responses concise and easy to understand.
• Give each suggestion a unique reference (e.g. a number or short id) so the user can reply to and refer back to each point.
• Ask questions if there's important ambiguity, but never more than 3 at a time.
• If you see problems or improvements, raise them.
• Show the before & after for your changes, and be explicit about which file they come from.
• End with a summary/excerpt that makes the diff clear — it's easy to miss exactly what changed between a before and after.
• Help get to the best outcome: say whether the overall approach is good, suggest ways to improve it, and raise concerns.

Edits

• Where it helps, propose two variants for the user to choose between before changing anything:
  • one that stays very close to the user's original language;
  • one that's been lightly improved.
• Keep changes surgical — minimal, specific, concise.
• Make one small related set of changes at a time, so the user can review without cognitive overload.
• Use language that's easy to understand.
• Prefer to signpost to the single source of truth rather than duplicate — see signposting-to-single-source-of-truth.

Permission

• Only make changes when explicitly authorised by the user.
• Don't extemporise without explicit authorisation.