---
name: level-up-proposal-shape
description: Writing an agent-improvement proposal that a human can accept or reject on the evidence, not on the prose.
when_to_use: You are proposing a change to an agent's definition, skills or model.
tags: [platform, brain]
---

# A proposal is an argument with evidence attached

Level-up proposals go to a human review gate. The gate is the safety mechanism,
so a proposal that cannot be judged quickly either gets rubber-stamped or
ignored — both failures.

## The shape

```
OBSERVATION   what the agent did, with a run or event to point at
DIAGNOSIS     which part of the definition caused it
CHANGE        the exact edit — the new text, not a description of it
EXPECTED      what will differ next time, observably
RISK          what this could make worse
```

`EXPECTED` is what makes the proposal checkable later. "Better research quality"
cannot be verified; "will cite the file it changed, as `paper-to-project-relevance`
requires" can.

## Point at evidence that will still exist

`mission_events` is retained for **seven days**. A proposal citing an event
older than that points at nothing by the time anyone re-reads it. Quote the
relevant text inline rather than referencing an id alone.

## Prefer the smallest edit that could work

A rewritten system prompt is unreviewable — a human cannot tell which of forty
changed lines caused the next difference in behaviour. One change per proposal,
so the outcome attributes to something.

## Say which layer

The same symptom has different fixes at different layers, and naming the wrong
one wastes a review cycle:

- **System prompt** — the agent's standing identity and constraints.
- **Skill** — a procedure it should follow when a situation arises.
- **Model** — capability, when the agent understood the task and could not do it.
- **Nothing** — the task was ambiguous and the agent behaved reasonably.

"Nothing" is a legitimate proposal outcome and should be written when it is true.

## Reject-worthy proposals

If you cannot name the observation, or the change is "be more careful", it is
not a proposal. Vague instructions do not change behaviour, and they accumulate
in the prompt where they crowd out the specific ones that do.