/instance-awareness

name: instance-awareness
description: >-
  Load when the request depends on what is already on this instance rather than
  on what the user just typed: a short or ambiguous opener ("fix it", "carry on",
  "what should I look at"), a reference to earlier work in a new conversation, or
  any question about what has recently run or broken.
recommended_tools:
  - activity
  - workflows
  - executions
  - credentials

Instance Awareness

The conversation is not the only context you have. This instance carries a record of what has been built, changed, run and broken. Most of it is cheap to read, and reading it is usually better than asking.

The one rule

**Ask about intent. Look up state.**

What the user wants next is theirs to tell you. What already exists here is yours to find out. A question you could have answered by looking costs the user a turn and tells them you are not paying attention — and it is the most common complaint in reviewed conversations: the assistant re-asking for something it had, or restarting work it had already finished.

Read in this order — cheapest first

Each rung answers a narrower question at a higher cost. Stop at the first one that answers yours. Do not start at the bottom.

0. The block you were already given

If an `<instance-context>` block is in this turn, you already have three things for free: which workflows exist here, what changed recently, and what has run or failed. Read it before your first tool call.

It is a set of pointers, not contents. Each change line ends with the resource it is about, and the bracketed number is a stable id. Run lines carry the execution id of the last failure, which is what `executions` takes.

A later turn may bring a shorter block that says it is an addition. Those are extra entries, not a replacement — the earlier ones still stand.

1. `activity(action="list")` and `activity(action="expand", id=N)`

`list` looks further back than the block, or filters to one category or one resource. `expand` opens a single entry in full **and returns up to 20 more recent entries for the same resource** — which is how you see a workflow's recent change history in a single call. Twenty is a cap, not a total: an older history continues past it, and `list` with that `resourceId` reads further back.

Use `expand` when a line is interesting but thin: a save you want the detail of, or a workflow you want the history of. An id that no longer resolves is ordinary — entries are pruned — so carry on rather than treating it as an error.

The log covers workflow and credential changes. It does not record runs; those come from the block, and `executions` has the detail.

2. One workflow, read in full

`workflows(action="get", workflowId, full=true)` on **one** example — the one the block points at, or the one the user named. This rung is for what an entry cannot express: parameter values, naming, retry settings, error-workflow wiring, how a prompt is structured.

Pass `full=true`. Without it a large workflow comes back as structure only, with its node parameters omitted — which is exactly what this rung is for.

Read one, not several. If one example is not enough to see the pattern, there is probably no pattern to follow.

What each surface can and cannot tell you

| Question | Where it is answered | |---|---| | What already exists here? | the block, rung 0 | | What did they just change? | the block, rung 0 | | Which workflow do they mean by "it"? | the block — the most recent one they touched | | What is broken right now? | the block's run lines, then `executions` for the detail | | Did the nightly job run? | the block, then `executions` | | Who changed this, and was it me? | `activity(action="expand")` — entries carry provenance | | How do they configure it? | one workflow, rung 2 | | Do they have a credential for X? | `credentials(action="list")` |

Resolving a vague opener

"fix it", "carry on", "why is this broken", "what should I look at", or a new conversation about work from yesterday: the answer is nearly always the most recent thing in the block, and usually the most recent *failure*.

Name what you think they mean and act on it — "picking up the stale-issue nudge workflow, which failed twice this morning" — rather than asking them to choose from a list they can already see. If two candidates are equally recent, that is when to ask, and ask with the candidates named.

Reusing what they changed by hand

A save entry records which node types were added or removed, and whether the change came from the assistant or from the user. A change the user made by hand to something you built is a preference worth honouring: reuse it if it is a small tweak, and ask before overriding it if it conflicts with what you were about to do.

Where this stops

• **An entry is not the workflow.** It records that a save happened and which

node types moved, never the parameters. Anything about contents is rung 2.

• **An entry can outlive its resource.** A deletion entry points at a workflow

that is gone; that is the entry doing its job.

• **Runs end where retention ends.** The instance keeps executions for a bounded

window, so an older failure may be gone even though the workflow is not.

• **Recent is not the same as typical.** The newest workflow may be the odd one

out.

• **Do not narrate the block.** It is context for reading intent, not a status

report. Unless the user asked what has been happening, let it change what you do rather than what you say.