instance-awareness

# 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.