# Writing Back Upstream



<a id="section-goal"></a>

Production cross-checks sources, and documentation lagging behind code is the normal case. By default the Agent corrects the knowledge from the code facts, so the knowledge is right but the original document stays stale. If you want the originals fixed too, ask the Agent to collect the differences as it goes and handle them together at the end.

```mermaid
flowchart LR
  diff["Document lags code"] --> fix["Knowledge follows<br/>the code facts"]
  diff --> log["Record in update-remote/<br/>context, judgment, suggestion"]
  log --> choose["After the task:<br/>you decide"]
  choose -->|authorized| write["Agent edits the original<br/>and reads it back"]
  choose -->|not now| sugg["Concise suggestion<br/>for the owner"]
```


<a id="section-setup"></a>

## Ask for it once

Add the instruction at the start of a task, or permanently in the `AGENTS.md` of the Context knowledge workspace:

```text
When a revision is caused by documentation lagging behind the code, record it
in update-remote/<date>-<topic>.md with the context, the judgment and the
suggested change. After the task, work through update-remote: find each
upstream document and either revise it or give a concise suggestion for me
to decide on.
```

Upstream documents then catch up promptly, and knowledge and originals do not drift apart for long.


<a id="section-judge"></a>

## Is the original actually wrong?

Before proposing an upstream edit, the Agent distinguishes three cases:

| Case | What happens |
| --- | --- |
| The knowledge misunderstood correct source text | Only the local page is corrected |
| A confirmed decision has not reached the document | The decision can be saved as a local note while the upstream change is considered |
| The conclusion is still uncertain | It is not written anywhere as fact |


<a id="section-write"></a>

## Making the edit

Neither approving knowledge nor fully managed mode authorizes a remote write. For each edit, the Agent shows the exact document, the affected passage, the before/after text, the reason and the knowledge it affects, and uses an authorization you have already given for that concrete edit or asks for one. It rereads the passage just before writing, adapts only within the authorized scope if someone else changed it, writes with its document tool and reads the result back.

The returned document then feeds the normal capture and update flow, so the local snapshot reflects what is really upstream. If the remote edit succeeded but the local build failed, the Agent resumes the local delivery rather than editing again. It does not post comments, notify groups or change permissions; when it lacks permission, it leaves you a concrete suggestion.

---

## Sources

- note:20261012/usage-practices.md · usage-practices.md L28–L30
- note:20261012/usage-practices.md · usage-practices.md L30–L37
- [context/packages/context/docs/guides/knowledge-updates.md L499–L505 · 3b0ce0a](<https://github.com/context4ai/context/blob/3b0ce0a0a1761f5fceb3bb48fb9dc29b54c0786b/packages/context/docs/guides/knowledge-updates.md#L499-L505>)
- [context/packages/context/docs/guides/knowledge-updates.md L501–L521 · 3b0ce0a](<https://github.com/context4ai/context/blob/3b0ce0a0a1761f5fceb3bb48fb9dc29b54c0786b/packages/context/docs/guides/knowledge-updates.md#L501-L521>)