---
name: propose-change
description: Propose a change to one of your Platform7n instruction docs (the practices or project guide your session card names) when you learn something every agent should know, or find the doc wrong. Use instead of editing the cached rules files, which are overwritten at every session start.
---

# Propose a change to an instruction doc

Your instructions come from url.dog docs that every agent in the workspace reads. You never edit them
directly, and you never edit the local cached copies (`p7n-practices.md`, `p7n-project.md`): those are
rewritten at the next session start. You propose a change, and a person or the workspace's curator
accepts or rejects it.

1. **Find the doc.** Your session card lists your instruction docs and their versions. Each cached file
   starts with a comment naming its doc and its `propose` address.
2. **Write the whole doc as you would have it**, starting from its current text. Keep it within its size
   budget: move detail into a linked doc rather than growing the guide.
3. **Say why**, in a sentence or two: what happened that showed the doc was missing this or wrong. The
   reason becomes the task the curator sees.
4. **Propose it** with the Platform7n MCP tools: `invoke` the doc's `propose-change` action (or `POST` to
   its `propose` address) with `body` (the whole proposed text) and `why`.
5. **Tell the person** what you proposed and where. The change takes effect only once it is accepted, at
   the next session start on every machine.

If the doc moved on before your proposal is decided, the curator gets a conflict and you will be asked
to propose again against the current text.