Back to docs

Tool Persona Update

Change a persona without rebuilding it.

Patches an existing custom persona. Only the fields you pass are touched; everything else is preserved exactly. Writes both stores a persona lives in and tells you which writes landed.

Why this exists

A persona is a set of judgements, and judgements get revised. A trait was set from a description that turned out to say something else. An attention pattern was declared thorough for someone the description calls a skimmer. A persona gets a Big Five profile months after it was created.

Without an update path, those corrections happen outside the system — someone edits a file, or nobody edits anything and the persona stays wrong.

Usage

{
  "tool": "persona_update",
  "params": {
    "persona_name": "sofia-mobile-navigator",
    "attentionPattern": "skim",
    "traits": { "patience": 0.15 }
  }
}

Returns which fields changed, where each store's write landed, and the values route if it moved.

{
  "persona": "sofia-mobile-navigator",
  "changed": ["traits(patience)", "attentionPattern"],
  "fileStore": { "written": true, "path": "~/.cbrowser/personas/sofia-mobile-navigator.json" },
  "cms": { "ok": true, "detail": "CMS put ok" },
  "note": "Both stores updated."
}

Parameters

parameter effect
persona_name Which persona. Required.
traits Partial trait map, merged over the existing traits rather than replacing them.
description Replaces the description.
attentionPattern targeted · f-pattern · z-pattern · exploratory · sequential · thorough · skim
accessibilityTraits Merged, not replaced.
bigFive All five factors. Moves the persona to the big_five values route.
ageRange, techLevel Demographics.

Supplying a Big Five profile changes what the persona can express

Values come from one of four routes, and they reach different numbers of motivational axes. A persona derived from cognitive traits reaches nine of thirteen — hedonism, power, universalism and the relatedness need have no cognitive trait pointing at them, so they sit at the 0.5 baseline.

Passing bigFive moves it to the Big Five route, which reaches all thirteen through published trait–value correlations:

{
  "tool": "persona_update",
  "params": {
    "persona_name": "chen-wei",
    "bigFive": {
      "openness": 0.33, "conscientiousness": 1,
      "extraversion": 0.2, "agreeableness": 0.67, "neuroticism": 0.33
    }
  }
}

The response reports valuesRoute: "big_five", and persona_values_lookup will show every axis populated with no unpopulatedAxes.

Attention pattern overrides the traits

attentionPattern is a declaration, and a declaration is what drives behaviour at runtime — it wins over whatever the trait vector implies. That is deliberate: it can encode something traits cannot, like a screen reader's sequential pass.

It is also worth setting carefully, because a declaration that contradicts the traits will change how the persona reads a page while the numbers say something else. persona_lookup reports the disagreement when there is one:

declared "thorough", but this persona's traits score "f-pattern" highest by 0.21
(reading 0.55, patience 0.7, satisficing 0.5). The declaration is in force at
runtime; the trait vector disagrees with it.

Two stores, and the response says which one took the write

Personas live in the file store the package reads and in the CMS. A persona updated in one and not the other produces the failure that is hardest to notice: two tools answering the same question differently, each internally consistent.

So the response never reports plain success. It names both stores:

{
  "fileStore": { "written": true, "path": "..." },
  "cms": { "ok": false, "detail": "no API key in session — the CMS copy was NOT updated" },
  "note": "File store updated; the CMS copy was NOT. They now disagree — re-run with a session API key."
}

What it refuses

  • Built-in personas. first-timer, power-user and the rest ship with the package and are shared by every install. Create a custom persona instead.
  • Unknown personas. list_cognitive_personas returns the roster.
  • Empty updates. At least one updatable field is required.

Related

From the Blog