# Changing what the agent is told

A prompt change lands in one of six layers, and which layer you edit decides who it reaches and how fast it can be undone. On a live call the cost is measurable rather than theoretical: instructions of 7,500 characters gave a first token in 1.2–1.8 seconds, 9,600 characters gave 2.3–3.4. Change one layer, place a test call, read the turn timings, keep the old text.

- **Status:** Available
- **Audience:** both
- **Channels:** phone, email
- **In the app:** #/calls, #/maya-rules, #/knowledge
- **Last verified:** 2026-09-10
- **Canonical:** https://connectbyjbrh.com/docs/workflows/prompt-change/

## The six places a prompt actually lives

There is no single prompt file. What the model is given on any one call is assembled per call by `voice_engine.brief()`, and the layers are resolved narrowest-last by `voice_style.resolve`. Editing the wrong layer is the usual reason a change appears to do nothing: a narrower layer is still overriding it.

| Layer | Set where | Reaches | Undo |
|---|---|---|---|
| Workspace behaviour | Connect Rules, Phone → Behaviour | Every call and every draft in the workspace | Restore the previous text; it applies from the next call |
| Default voice profile | Voice Lab | Every line with no more specific profile | Select the previous profile |
| Profile by purpose | Voice Lab, per `inbound | service | transactional | promotional` | One kind of call | Detach the profile from that purpose |
| Profile by line number | Voice Lab, per line | One number | Detach it from the line |
| Profile on the contact | `contact.facts.voice_profile` | One person, every time they ring | Clear the field on the contact |
| The Lab's draft | Voice Lab, on a test call only | That test call and nothing else | Discard the draft — it was never live |

Three more inputs behave like prompt text without being edited as prompt text: Knowledge (the grounding facts), Memory (four tiers, narrowest first) and standing instructions. A change to any of them changes what the model reads, and each is capped — knowledge at 4 facts and 2,000 characters, memory at 700, the contact block at 600 — so adding a fifth fact drops another one rather than lengthening the call's prompt.

## The chain a change runs through

1. TRIGGER — somebody edits behaviour text, a profile, a knowledge source, a memory or a standing instruction.
2. USER / EXTERNAL EVENT — the edit is a person's, made on a screen; no external event starts this flow.
3. AUTH / WORKSPACE RESOLUTION — the session resolves to one workspace; an Owner edit and a customer edit reach the same service by different paths, `tenantAdapt` rewriting the customer's.
4. INGEST / REQUEST — the new text is validated and saved through the service that owns it, not written into a prompt file.
5. CANONICAL RECORD — the change lands on the workspace's settings, the profile row, `connect_memory` or the knowledge source. Calls already in progress are untouched.
6. CLASSIFICATION / RESEARCH / REASONING — none. A prompt edit is not reasoned about; it is stored.
7. KNOWLEDGE + MEMORY + RULES — the next call assembles a brief from the new values, inside the character budgets above.
8. AUTONOMY / APPROVAL — unchanged by this flow. A prompt cannot widen what Connect may do; autonomy modes and scopes decide that separately.
9. ACTION / PROVIDER — the first call after the edit sends the new instructions to the realtime model as session instructions.
10. RESULT — `session.instructions_chars` records the size actually sent, so the cost of the edit is on the record rather than estimated.
11. RELATIONSHIP / TIMELINE / MEMORY — the resolved settings are snapshotted on `call.quality`, which is why a review months later judges what ran rather than what is configured now.
12. AUDIT / USAGE / NEEDS YOU — the edit is an audited change with actor, target and before/after; the call it affects carries its own cost and timings.
13. NEXT — read the turn timings from the first call under the new text before editing anything else.

## What extra characters cost

Every character is paid for twice. Once in time to first token, and once per turn: a Live session is re-billed for its entire context on every reply, and production calls are 92% carried context by input token. A paragraph added to the workspace behaviour is charged on turn twelve as much as on turn one.

- 7,500 characters of instructions: first token 1.2–1.8 s.
- 9,600 characters: first token 2.3–3.4 s.
- The floor underneath both is the model's own — a 3.3 s median reply on the best measured call, on the default Gemini 3.1 Flash Live.
- A human voice profile block stays under about 2,500 characters for the same reason.

> **Careful** Two behaviours were measured as model-limited and rolled back rather than left in the prompt: respect-word cadence, where a rendered cadence rule changed 6 of 8 replies and answered an English sentence in Telugu, and murmur handling, where the model writes a mumble as a word and answers it and a prompt sentence changed nothing. Characters spent on either buy latency and no behaviour.

## Proving the change did something

1. Note the current `instructions_chars` and the last few calls' reply medians before you edit.
   - Result: You have a baseline that is a measurement rather than a memory.
2. Make one edit, in one layer.
   - Result: When the numbers move you know what moved them. Two edits at once produce a result nobody can attribute.
3. Place a test call from the Voice Lab and let it run several turns.
   - Result: `TurnClock` posts a `turn_timing` event per reply, measured on the wire from the caller's last word to the first audio back — never from transcript rows, which arrive when a sentence is complete and once showed '8 ms' beside replies the caller waited seconds for.
4. Open the review for that call.
   - Result: `voice_quality.review` lists deterministic findings — slow replies, long gaps, ignored interruptions, repetition, stock phrases, wrong script — each with the setting that addresses it. Findings marked `MODEL_LIMITED` are counted and do not lower the score, because no control you can turn would fix them.

One published comparison is worth holding as the shape of a good result. After the 2026-09-06 change to the opening — the greeting is spoken with the caller's audio muted, and the instructions say the opening has already been said and ask for one thought, one question, under 25 words — re-introductions went from 1–4 per call to none, words per reply from a 23–40 median to 19, stacked questions from 2–4 to none, and there was no latency regression.

## Rolling back, and what can fail

**The edit changed nothing** — A narrower layer is winning. Check the profile on the contact and the profile on the line before editing the workspace text again.
**Replies got slower** — The prompt grew. Compare `instructions_chars` before and after; the relationship between size and first token is steep between 7.5k and 9.6k.
**A knowledge fact stopped appearing** — The budget is 4 facts and 2,000 characters. Adding one pushed another out, and nothing errored.
**Guidance never reached a call in progress** — On the default model the session is immutable, so mid-call notes and supervisor guidance are recorded as undelivered rather than quietly lost.
**Rollback is not instant** — A call in progress keeps the brief it was given. The old text applies from the next call, not from the moment you save.

Keep the previous text somewhere you can paste it back. There is no version history on behaviour text, and a rollback is a new edit made by somebody who still has the words.

## Questions

### Does a prompt change affect email as well as calls?

Workspace behaviour, Knowledge, Memory and standing instructions are shared, so yes. Voice profiles and the Voice Lab's steering knobs are the phone's alone — they become session parameters and instruction lines for a speech-to-speech model, and have no meaning in a drafted reply.

### Can I test a change without any real caller hearing it?

Yes. The Lab's draft applies to a test call and to nothing else; it sits at the narrowest point of the resolution order deliberately, so it cannot leak into live traffic and cannot be left switched on by accident.

### How much of a slow reply is the prompt's fault?

The review answers that rather than leaving you to guess. When the model's own first token accounts for 60% of the wait, the finding says so and offers no control, because trimming the prompt further would not recover the time.

## Related

- [Telling the voice how to speak](https://connectbyjbrh.com/docs/phone/speaking-guide/)
- [The Voice Lab](https://connectbyjbrh.com/docs/phone/voice-lab/)
- [What a setting cannot change](https://connectbyjbrh.com/docs/phone/model-limits/)
- [Tuning the voice, end to end](https://connectbyjbrh.com/docs/workflows/voice-tuning-cycle/)
- [What every character of a prompt costs on a live call](https://connectbyjbrh.com/research/prompt-size-and-first-token/)
- [Knowledge in Connect](https://connectbyjbrh.com/docs/knowledge/)
- [Proving a change did not break anything](https://connectbyjbrh.com/docs/workflows/regression-check/)

## What this page is based on

- `backend/app/voice_style.py` — resolution order, session options, style block
- `backend/app/voice_engine.py` — `brief()` and the per-call assembly
- `docs-source/sources/PHONE.md` §6, §7, §10 — instruction size, budgets, the gap audit
- Connect capability registry (docs-source/facts.py)