Kowalah

View saved version →

---
name: ai-estate
description: Review and maintain the organisation's AI estate — which AI tools and platforms it actually has, what people have built and switched on in them (connectors, skills, plugins, projects, agents), how each is held (licences, seats, contracts, DPAs), which are unsanctioned or risky, what renews soon, and where each is used in the business. Use for "what AI tools do we have", "what's our shadow AI", "which tools train on our data", "what renews this quarter", "is ChatGPT approved", "add Granola to the register", or any audit of AI tools and licences.
---

# AI estate

For the AI Ops lead, the core team, the CIO or whoever is accountable for which AI the
organisation uses. The first question they have to answer is **what have we actually got**,
and the second is **what should we worry about**. This skill answers both from the systems
register, and keeps the register true.

## Read the register before you ask

**`kowalah_get_systems`** returns the register: every system, whether it has AI in it,
how the organisation holds it (arrangements), how many live process steps use it, and a
`flags` block. Pass `ai_only: true` for the AI Register view. Read it first, and ask the
user only about what it doesn't hold.

A register that looks short is usually a finding in itself. If the organisation plainly
uses tools that aren't recorded (the ones you can see connected in this session are a good
first check), say so before reviewing what is there.

## Read the flags in this order

1. **`risks`**, highest severity first. `employee_contracted` is the one that matters most:
   a personal plan used for work means no DPA, no admin control and no audit trail. That is
   shadow AI, and it is the headline. `trains_on_data` without `dpa_in_place` comes next.
   `prohibited_in_use` means a tool the organisation banned is still held.
2. **`unreviewed`** — arrangements nobody has made a decision on. Unreviewed is not
   approved. Count them and say so.
3. **`ai_without_arrangement`** — AI the organisation uses with no record of how it holds
   it. Each one is a question: who pays, on what plan, under what terms?
4. **`not_in_model`** — systems in the register that no process step runs on. Either the
   work that uses them hasn't been mapped, or it's shelfware. Both are worth saying.
5. **`renewals_due`** (admins and core team only) — renewals in the next 90 days. Pair each
   with its risks and its usage: a renewal is the moment to fix an arrangement, and a tool
   used in no step is a candidate not to renew.

**A null is "not assessed", never "no".** `dpa_in_place: null` means nobody has checked,
which is different from `false`. Report unassessed fields as gaps to fill, not as passes.

## What's been built and switched on

The systems register says which products the organisation holds. **`kowalah_get_ai_estate`**
says what's deployed inside them: connectors, skills, plugins, projects, agents, automations
and apps, who uses each, and the process steps they run. Read its `gaps` first:

- **`unsanctioned`** — assets on a platform the organisation hasn't approved or has
  prohibited, personal ones first. This is the shadow-AI list, and it joins the two
  registers: a personal Gmail connector on an unreviewed Claude plan is one line here.
- **`personal`** — one person's own tools used for work, with their platform's standing.
- **`undecided`**, **`no_owner`**, **`scope_unknown`** — what nobody has decided. Admins and
  core team settle these with `kowalah_record_ai_assets` (by `id`: owner, status, scope).
- **`not_in_model`** — agents, skills, automations and apps that run no process step. Either
  the step hasn't been mapped or the tool isn't earning its keep.
- **`needs_auth`** — connectors installed but never connected, or disconnected.
- **`stale`** — nobody has shared it from their session for 90 days: likely retired.
- **`suggested_step_links`** — steps whose text names an agent, skill, automation or app
  that isn't linked to them yet ("Brian drafts the reply"). Confirm each with the process
  owner, then link it with `kowalah_record_ai_assets` (`id` plus `serves_step_ids`). This is
  the quickest way to turn the free-text model into one that knows what runs each step.
- **`platform_unknown`** — assets with no platform, so the shadow-AI check can't see them.
  Usually the platform isn't in the systems register yet: add it with `kowalah_save_system`,
  and the next `my-ai-tools` run links everything on it.
- **`reaches_unregistered`** — connectors to a system the register doesn't hold (Figma,
  Sentry). Add the system if the organisation depends on it.
- **`acts_unsupervised`** — connectors that `can_act` (send, edit, delete) with no human
  approving. This is the one to read out first after shadow AI: ask whether anyone signs
  off on what it does, and record the answer as `human_approval`.
- **`connection_concentration`** — one person's login holds three or more of the
  organisation's connectors. If they leave or their account is locked, all of them stop at
  once. Admins and core team see who; members see only counts.
- **`in_house`** — what the organisation built itself. Nobody outside maintains these, so
  each needs a named owner and a `maintained_at` home (a repo or a folder).

Each asset also shows its `origin` (anthropic, kowalah, vendor, in_house, unknown), its
`version` and where it's `maintained_at`. Sessions fill these in when they can see them.
How each is held is a decision, set by admins and core team with
`kowalah_record_ai_assets`:
- `connection_holder_user_id`: whose login the connector runs on. A member can say their
  own connector runs on their own login.
- `access_level`: `read_only` or `can_act`
- `human_approval`

Leave any of these unset rather than guessing. An unknown access level is a gap, not
read-only.

Each asset shows its `platform` and, for a connector, the systems it `reaches`. Pass
`unit_id` to see one part of the business, or `origin` to see, say, only what was built in
house.

**What each tool has delivered.** Every asset carries an `outcomes` count, and `id` returns
the outcomes themselves with totals. An agent that runs live steps and has no outcomes
hasn't been shown to earn its keep: before a renewal or a retirement, ask its owner what it
has delivered, and record it with the `outcomes` skill.

**Assets no assistant session can see** — agents on the Agent Hub or a model API, Zapier or
n8n automations, Copilot agents, Slack bots — are added by hand: `kowalah_record_ai_assets`
with `source: "manual"`, the kind (usually `agent` or `automation`), and the `system_id` of
the platform it runs on. Then link the steps it runs.

**The register is only as complete as the people who have shared their tools.** It is
filled by the `my-ai-tools` skill, which each person runs in their own assistant: it shows them
their setup, fixes what's half connected, and records what they choose to share. There is
no background collection. If the register is thin, or `stale` is long, the fix is to ask the
team to run `my-ai-tools` (a one-line message from the AI lead is usually enough), not to
fill the register by guessing. If it's complete but nobody has said what things are for,
ask the owners of the live, organisation-wide tools to run its part two.

## Where each tool is used

`kowalah_get_systems` with an `id` returns `used_in`: every live step and process that runs
through that system. This is what makes the register more than a list: "Claude is used in
12 steps across 4 processes" tells the reader what a problem with Claude would touch. Use it
when a risk is serious, before a renewal, and whenever someone asks what a tool is for.

When a step runs on a tool but the step doesn't say so (the tool is named only in
`platform_detail`, or not at all), set `system_ids` on `kowalah_save_process_step`. It
replaces the whole set, so pass every system the step uses.

## Keeping the register true

**`kowalah_save_system`** adds or updates a system and its arrangements. Admins and core
team only; for anyone else, read the register and offer `kowalah_create_opportunity` for
the change.

- Search before adding (`kowalah_get_systems` with `search`). Saving a name that's already
  in the register returns the existing system rather than a duplicate, and a name in
  Kowalah's catalogue uses the catalogue system: record the organisation's arrangements on
  it. Only pass `own_copy: true` when the organisation needs its own record, for example to
  mark a catalogue CRM as having `embedded` AI switched on.
- **One system, several arrangements.** "Claude Team, 50 seats, organisation-contracted,
  DPA in place, approved" and "Personal Max plans, employee-contracted, unreviewed" are two
  arrangements on one system. Don't create a second system for the second way of holding
  it.
- **`ai_capability`** is a spectrum, not a yes/no: `embedded` for AI switched on inside a
  non-AI product (Slack AI, HubSpot Breeze), `native` when the product is AI (Claude,
  ChatGPT), `infrastructure` for model or API access (Claude API, Azure OpenAI). `embedded`
  is the category people forget, and it is often the largest.
- Record only what the user actually knows. Leave the rest unset rather than guessing, and
  never set `sanctioned_status` to approved on the user's behalf: only the organisation can
  approve a tool.
- Retire a tool with `status: "archived"`; systems are not deleted.

## What a good review says

1. **What the organisation has** — the count of AI systems and how they're held, what has
   been built in them, and what's plainly missing from either register.
2. **What to worry about** — the risks, named, with where each tool is used; what acts
   with nobody approving; whose single login everything depends on.
3. **What nobody has decided** — the unreviewed arrangements and the unassessed fields.
4. **The next decision** — usually a renewal, a tool to approve or retire, or a register to
   complete. Name who has to decide.

## Scope and permissions

Everyone in the organisation can read the register. Cost, payment route and renewal dates
are shown to admins and core team only; the response's `commercial_fields` says which you
got. If they're hidden, say so rather than implying the organisation has no costs recorded.

If the user belongs to more than one Kowalah organisation, pass `organization_id`. Call
`kowalah_get_update` with no query to list their organisations, then ask which one.

View saved version →

---
name: kowalah-setup
description: Connect the Kowalah MCP server and work out what the signed-in account can see. Use when the Kowalah plugin has just been installed, when Kowalah tools return nothing or error, when the user asks how to connect Kowalah, or when someone wants to start mapping an AI operating model from scratch.
---

# Setting up the Kowalah connection

The Kowalah plugin talks to `https://mcp.kowalah.com/api/mcp` over authenticated HTTP.
Every tool is scoped to the organisations the signed-in user belongs to — there is no
anonymous or read-only mode.

You do not need an existing Kowalah engagement. Signing in creates an account, and if
nobody from the user's company is here yet it creates an organisation for them too, with
them as its admin and an empty operating model to fill.

## Connecting

1. **Installing the plugin doesn't connect it.** The plugin bundles the `kowalah` MCP
   server, but the user still has to connect it. In Claude: open the plugin from
   **Customize → Plugins** and go to its **Connectors** tab.
   - **Not connected** — connect it there.
   - **Not added** — add it there, then connect. On a Claude Team or Enterprise plan a
     workspace owner usually has to add it for the organisation first, under
     **Organization settings → Connectors** with the URL `https://mcp.kowalah.com/api/mcp`.
     If the user can't add it, that's who to ask.

   In Microsoft 365 Copilot: in Cowork, turn the Kowalah plugin on under
   **Customize → Plugins**, then sign in when the Kowalah connector asks. In Copilot Chat,
   add the Kowalah agent, and it asks you to sign in the first time it uses Kowalah. If
   Kowalah isn't listed in either, the organisation's Microsoft 365 admin has to make it
   available first.

   In another assistant, connect the Kowalah app or connector the way that assistant asks.
2. **Sign in, or sign up — with a work email address.** An email Kowalah doesn't already
   know is fine; an account is created automatically and you do not need to be invited
   first. The email domain decides where you land, so a personal address (gmail, outlook)
   will not reach a company's organisation even if one exists.
3. Approve the connection.

## Then work out which organisation they landed in

Every Kowalah account belongs to an organisation — there are no personal accounts. On
sign-up the user is placed in one of two, and the difference changes what you should do
next:

- **Their company's organisation**, if its email domain is already registered with
  Kowalah. They join it, usually as a `member`.
- **A new organisation created for them**, if it isn't. They are its sole admin, and it
  contains nothing but an automatically-created root unit.

Both authenticate identically and both are legitimate. Establish which one before doing
anything else, because the same empty result means opposite things in each.

Run **`kowalah_get_update`** with no query. A working connection returns `kind: "home"`
with the user's identity, their `organizations` (each with `id`, `name` and `role`), and a
role-appropriate rollup.

### Read three things off it

**Which organisations they belong to.** If more than one, several tools need an explicit
`organization_id` — ask which one each time rather than guessing.

**Their role.** This gates `kowalah_get_update` only: `admin` and `core_team` see
everything in the organisation, `member` sees their own opportunities plus items they are a
stakeholder on. It does **not** gate the operating model, vision map, accelerator library
or process detail — anyone in the organisation can read all of those. Writes are
permission-checked separately, and where a user cannot edit something the tools route them
to a proposal rather than refusing. An admin is a cross-cutting editor in their own
organisation, so a sole admin in a new organisation can author the whole model.

**Which of the two organisations they landed in.** Check this by *shape*, never by name.

**The organisation's name proves nothing.** A newly-created organisation is *named* from
the signer-up's email domain, so a work-email sign-up produces one named after their own
employer — indistinguishable at a glance from the company's real organisation, which may
exist separately under a near-identical name. Only a personal email address produces the
obvious *"Sam's organization"* giveaway.

The reliable tell that this is a **new, empty organisation** is all four together:

- exactly **one** organisation, and `role` is `admin`
- `kowalah_get_operating_model` returns **one unit and zero processes** — note this is
  *not* `kind: "empty"`, because a root unit is created automatically, so the model looks
  present but is bare
- `kowalah_get_vision` returns `kind: "empty"`
- `kowalah_get_update` shows no projects, deliverables or expert requests despite the
  `admin` role that would reveal them

## What to do about it

Say plainly which of the two they are in, then ask what they expected, because that is
what decides the next step.

### They are in a new organisation of their own, and that is fine

This is the normal starting point for someone with no Kowalah engagement: an AI Operations
Lead, an internal forward deployed engineer, or anyone who owns AI delivery inside a
business and has nothing mapped yet. They are the admin, the model is empty, and they can
author all of it.

Offer to start. The first useful move is one org unit and its real processes, not an
attempt at the whole company:

- `kowalah_save_org_unit` to add the units under the root
- `kowalah_save_process` and `kowalah_save_process_step` to capture how work actually runs
- `kowalah_create_opportunity` to log what is worth automating as it comes up

Build it a function at a time, in the conversation where they are already describing how
their business works. Coverage matters more than depth early on — a shallow map of several
functions is worth more than a deep map of one.

What a solo model cannot do is check itself. It is one person's account of how the
business runs until the people who own those processes confirm their own, which is what
bringing the rest of the organisation in is for. Mention that when it becomes relevant,
not up front.

### They expected their company's organisation and did not get it

If their company already works with Kowalah, or colleagues are already using it, landing
in a new organisation of their own is the wrong outcome. Their work would go somewhere
nobody else can see.

Say so before they start building. The resolution is their Kowalah contact or their
organisation's AI lead attaching the account to the right organisation, and it is worth
doing first rather than migrating later.

### They are in their company's organisation

The working case. If the model or vision come back `kind: "empty"` here, the connection is
fine and nothing has been authored yet. That is Define-phase work the Kowalah team does
with the client, so don't offer to build it from scratch — check with their Kowalah
contact instead.

Once they're connected, offer `my-ai-tools` as a natural next step: it shows them which AI
tools their assistant has, fixes anything half set up, and lets them share their setup with
the organisation's AI register. Offer it once; it's optional.

## If something fails

- **No Kowalah tools at all, or every call fails** — the plugin is installed but its
  connector isn't connected. The skills load either way, so this is easy to miss. Walk them
  through step 1 of Connecting; if it shows *Not added*, they need their workspace owner.
- **401 / authentication error** — the session expired. Re-authenticate.
- **`User not found for Clerk user: …`** — sign-in worked, but the matching Kowalah
  account record was never created. This is a provisioning failure, not something the user did.
  Their Kowalah contact resolves it.
- **`User … has no active organization memberships`** — signed in, but attached to nothing
  at all. Rare, and also a provisioning failure. Same route.
- **Tools succeed but return nothing** — usually the new-organisation case above. Work out
  which of the two situations it is before treating it as a problem: for someone starting
  fresh it is the expected state and the answer is to start mapping.

View saved version →

---
name: my-ai-tools
description: See which AI tools you use in your assistant (Claude, ChatGPT, Codex and others) — connectors, apps, skills, plugins, projects — check they're set up properly, and share them with your organisation's AI register. Use for "what AI tools do I have", "what's connected", "is my setup right", "add my tools to the register", "my AI lead asked everyone to share their tools", or when someone has been asked to take part in an AI tools review.
---

# My AI tools

For anyone in the organisation. Most people's AI setup has grown one connector and one skill
at a time, and nobody, including them, has the full picture. This skill shows them theirs,
fixes what's half set up, and, with their say-so, adds it to the organisation's AI register
so the AI lead can see what's actually in use.

**What this skill sends, and when.** Only what the user approves leaves the conversation,
and only to their own organisation's AI register in Kowalah, with the
`kowalah_record_ai_assets` tool: first a list of tool names, kinds and ids, and then, if they
choose to do part two, their own answers about each tool. Nothing is sent before the user
has seen exactly what will be saved and said yes. If they say no, or say nothing, nothing is
sent.

## 1. Say what you'll do, and what you won't

Before looking at anything, tell them in two or three sentences:

- You'll list the connectors, skills, plugins and projects **this session** can see, in
  whichever assistant they're using.
- Only **names and ids** get recorded. You won't read or record what's inside a skill, a
  project or a conversation.
- They'll see the list first and choose what to share. Anything personal stays out unless
  they say otherwise.

Then ask whether to go ahead. If they'd rather just see their setup without sharing
anything, do step 2 and step 6 and send nothing.

## 2. List what this session uses

Work from what you can actually see in this session, not from memory or guesses. Each
assistant shows different things; list what yours shows and nothing it doesn't:

- **Connectors** (called apps in some assistants) — each one's name, and its id when the
  assistant shows one. Note its state: connected, needs authorising, disconnected, setup
  not finished.
- **Plugins** — name and id as the assistant shows it (in Claude, `plugin_…`), and the
  skills inside each.
- **Skills** — name, and id where there is one (in Claude, `skill_…`). Skills built into
  the assistant by its maker are recorded by name.
- **Projects** — you will usually see an id but not a name.
- **Custom GPTs aren't recorded.** They are being retired; if the work matters, record what
  replaces it.

If you can't tell what something is, or the assistant shows you very little of its own
setup, say so plainly and record only what you're sure of. A short honest list beats a
long guessed one.

**Leave out** built-in and local tools: memory, the file system, the browser, widgets,
anything running on their own computer. They aren't the organisation's AI estate.

**Never describe or send what's in a project, a skill or a chat.** For a project, record its
id and ask the user what it's called. If you can tell a project is personal, don't list it
for sharing at all.

Show the list grouped by kind, with anything that needs attention marked. Keep it scannable:
a table per kind, or a short list, not a paragraph per item.

## 3. Let them choose

Ask which to share. Make it easy: "all of these, except …" is the usual answer.

- **Personal things are out by default.** A connector to their own Gmail, a personal
  project, a skill they wrote for home. Offer once, plainly: sharing a personal tool as
  *personal* helps the AI lead see where people are using their own accounts for work, but
  it is their call.
- **Anything they haven't seen, you don't send.**
- **Confirm the final list.** Show exactly what will be sent (each item's name, kind and id)
  and ask "Send these to your organisation's AI register?" Only a clear yes counts.

## 4. Record it, and keep this pass quick

Once they've confirmed the list, call **`kowalah_record_ai_assets`** with `surface` set to
where this session runs and only the items they approved. Use the surface you're actually on:

| Assistant | `surface` |
|---|---|
| Claude on the web, desktop, Claude Cowork, Claude Code | `claude_ai`, `claude_desktop`, `cowork`, `claude_code` |
| ChatGPT on the web or desktop, Codex | `chatgpt`, `chatgpt_desktop`, `codex` |
| Microsoft 365 Copilot (Chat or Cowork), Gemini | `copilot`, `gemini` |
| Anything else, or you're not sure | `other` |

Never pick a Claude surface for another assistant. `other` is the honest answer when it
doesn't fit: the tools are recorded with no platform, which is a gap someone can fix, not
a mistake someone has to find.

For each item:

- `kind`, `name`, and `external_ref` whenever there is an id. The id is how the register
  recognises the same tool next time, and across the places they use it.
- Plugins **before** the skills inside them, with `parent_external_ref` on each skill.
- `connection_status` on connectors.
- `scope: "user"` on the personal items they chose to share.
- `origin` where you know it: `anthropic` for Claude's own built-in skills, `vendor` for
  another assistant's own built-in tools and for a connector's maker, `kowalah`, or
  `in_house` for something the organisation built.

You don't need to say which platform anything runs on: what this session uses is put on
the platform the surface runs on (Claude, ChatGPT, …) when the organisation's systems
register holds it, and each connector is linked to the system it's named for. If the
response says the platform isn't in the register, tell them: their AI lead can add it.

The response has one short line per item: **new** or **seen again**, its gaps, and
`ask: true` on the ones nobody has described yet (`ask_about` is how many). For those, ask
**one** quick question in this pass: is it just them, their team, or provided to everyone?
That's `scope`. Everything else waits for part two.

This first pass has to stay fast, or people won't run it. Someone running it for the
second time should be done in a minute.

**Some fields are for admins.** Owner, status and organisation-wide scope are set by admins
and core team (or the tool's owner). If Kowalah won't accept one of those values from this
user because of their role, it records the tool without that value. Tell the user which
value wasn't saved, and that their AI lead can set it.

## 5. Part two: what each tool does (when there's time)

A register of names says what exists, not what it does. Part two fills that in, and it's
**separate** from the first pass so capture stays quick. Offer it at the end ("have you got
five minutes to say what a few of these are for?"), run it on a re-run, or when the AI lead
asks from `ai-estate`. Never make it a condition of sharing.

Work only on items with gaps, a few at a time, **organisation-wide and live ones first**.
Before recording anything they tell you here, say what you'll save against which tool, and
save it only if they agree:

- **What's it for?** Their words become `description`. Never write one yourself from what a
  skill or tool contains.
- **Does it do a job in one of the organisation's processes?** If so, which step: find it
  with `kowalah_get_process` and pass `serves_step_ids`. This is how "Brian drafts the
  replies" becomes a real record on that step. `kowalah_get_ai_estate` lists
  `suggested_step_links`, steps that already name the tool in their text, so start there
  and ask the person to confirm each one.
- **For a connector: whose login does it run on, can it act** (send, sign, write) **or only
  read, and does anyone approve what it does first?** Record the answers as:
  - `connection_holder_user_id`: their own id, for their own login
  - `access_level`: `read_only` or `can_act`
  - `human_approval`

  Record only what they actually know, and leave the rest unset: "not sure" is a gap, not
  read-only. They can set these on their own personal tools. For shared ones, admins and
  core team decide, so put what the person said in `notes` instead.
- **Has it saved them time, or made something possible?** If they say so, offer to record
  it with the `outcomes` skill: on the step it serves, linked to this tool. Take their
  figure and how they know. Don't push for a number they don't have.

Stop when they've had enough. Whatever's left shows as a gap for next time.

## 6. Give something back

This is why it's worth their time. From what you listed:

- **Connectors that need authorising or have disconnected** — name them and say how to fix
  it in their assistant's connector or app settings. Installed-but-never-connected is common
  and usually an oversight.
- **Duplicates** — the same skill in several plugins, or an account skill that a plugin
  now provides.
- **Something already exists** — if they described a job a tool of theirs half-does, check
  `kowalah_find_accelerator`; there may be a better one off the shelf.
- **The organisation's position** — if a tool they use sits on a platform the systems
  register shows as unreviewed or prohibited (`kowalah_get_systems`), tell them straight.
  Not as a telling-off: they are the reason the AI lead can now sort it out.

Close with one line: what was shared, and what (if anything) they should do next.

## Running it again

People's setups change. Running this again is how the register stays current: known tools
are simply "seen again", and only new ones get questions. It only ever runs when the user
asks for it. If the AI lead wants a refresh, `ai-estate` shows what has gone quiet and they
ask the team to run it.

## Scope and permissions

Anyone in the organisation can share their tools. Everyone can read the register with
`kowalah_get_ai_estate`, but others' use shows as counts, not names, unless you are an
admin or core team.

If the user belongs to more than one Kowalah organisation, pass `organization_id`. Call
`kowalah_get_update` with no query to list their organisations, then ask which one.

View saved version →

---
name: outcomes
description: Record and report the value AI has actually delivered — time saved, cost reduced, revenue won, adoption milestones — on any work (a process step, a process, a unit, an opportunity, the whole organisation, a Kowalah deliverable), with what produced it and which vision measure it counts towards. Use for "we're saving 5 hours a week on this", "log that win", "what value have we got from AI", "what has this agent delivered", "how are we tracking against our success measures", or verifying a claimed outcome.
---

# Outcomes

An outcome is value that has actually happened, not value a use case is expected to
deliver. Expected value belongs on the opportunity's ICE score. This skill records the real
thing when someone reports it, and reports what's been realised when someone asks.

The reader who matters is whoever has to stand behind the number: the AI lead reporting to
the board, or the sponsor deciding whether to fund the next phase. So record in a way that
survives their questions.

## Recording one

**`kowalah_save_outcome`** records an outcome. Anyone in the organisation can record one.

**Put it on the work it happened in.** `on` is what the value is on:
- `process_step`: "Koko's triage saves two hours a month" is on the triage step. This is the
  most useful place, because the process then shows what it has delivered.
- `process`, `org_unit` or `opportunity` when the value is wider than one step.
- `organization` only for organisation-wide milestones ("80% of staff active weekly").
- `deliverable` or `expert_request` for value from a piece of Kowalah's work.

Find the id first: `kowalah_get_process` for steps, `kowalah_get_operating_model` for
units. Members can only record on a deliverable or expert request they're a stakeholder on.

**Link what produced it and what it counts towards.** If an agent, skill or automation
delivered the value, set `ai_asset_id` (from `kowalah_get_ai_estate`). That's how the estate
can say which tools are earning their keep. If it moves one of the vision's success
measures, set `vision_measure_id` (from `kowalah_get_vision`).

**Ask for a figure, and make it comparable.** With a number, always set:
- `value_unit`: hours, count, percent or currency
- `currency` for money, in any ISO currency: record euros as EUR, not converted
- `period`: `one_off`, or how often it recurs

Without these, the outcome is counted but can't be added up. "Saves two hours a month" is
`value: 2, value_unit: hours, period: monthly`. With no figure at all, still record it: a
milestone with a good narrative is an outcome.

**Ask how they know, and record the answer as `basis`.**
- `estimated`: a judgement
- `sampled`: timed on a few cases
- `measured`: from a system

Don't upgrade a guess. "About five hours, I reckon" is `estimated`, however confident the
user sounds. An honest estimate is worth more than a measurement nobody can reproduce. Put
the evidence in `evidence_url` if there is some.

**Write the narrative in their words:** what changed, for whom, and how they know. One
paragraph is plenty. `source` is `client` for the organisation's own work (the default),
`kowalah` for Kowalah's, and `joint` for both.

## Claimed and verified

Every outcome starts as a **claim**. Admins and core team can **verify** one (`verify:
true`), and it's recorded in their name. That's the organisation standing behind the
number. Anyone else who wants a claim verified should ask an admin or core team member.

- Changing a verified figure (value, unit, period, basis, or what it's on) makes it a claim
  again, and the tool says so. Tell the user it needs verifying again.
- Only the person who recorded an outcome, or an admin or core team member, can edit or
  remove it. Removing keeps it in history. Give a `reason`.
- Never verify on someone's behalf, and never describe a claim as verified.

## Reporting what's been realised

- **One process:** `kowalah_get_process` returns `outcomes` for the process and its steps.
- **One tool:** `kowalah_get_ai_estate` shows each asset's outcome count. With an `id`, it
  returns the full list.
- **Against the vision:** `kowalah_get_vision` returns each success measure with its
  baseline, target, current reading and `progress`.

**Read `totals` by unit, and keep what they keep apart:**
- **Claimed and verified.** Lead with verified. Then say how much more is claimed but
  unverified.
- **Recurring and one-off.** `recurringPerYear` is recurring value annualised. `oneOff` is
  one-off value. Adding them together gives a number that means nothing.
- **Different units.** Hours, pounds and euros are separate lines, never converted or
  summed.
- **`notComparable`.** These outcomes have no unit or period. Count them, say they couldn't
  be added up, and offer to fill in the figure.

**Say the basis.** "About 400 hours a year, mostly estimated" is honest. "400 hours a year"
over a set of guesses is not. If most of the value is estimated, the next step is usually
to sample one step properly.

**A missing outcome is a finding, not a zero.** An agent that runs three live steps and has
no outcomes hasn't been shown to be worthless: nobody has recorded what it does. Ask its
owner. The same goes for a vision measure with no current reading: say it hasn't been read,
not that nothing has moved.

## What a good report says

1. **What's verified**, by unit, with what produced it.
2. **What's claimed on top**, and its basis.
3. **What should have an outcome and doesn't:** live AI with nothing recorded, measures with
   no current reading.
4. **The next step:** usually someone to verify, a step to sample, or an owner to ask.

If the user belongs to more than one Kowalah organisation, pass `organization_id`.

View saved version →

---
name: process-diagnostic
description: Read one business process honestly — where its cycle time actually goes, how many handoffs it has, and what has never been measured. Use for "walk me through this process", "why does this take so long", "where are the bottlenecks in X", or before proposing any change to a process.
---

# Process diagnostic

For the person who owns a process and has to decide what to do about it. This is the read
that comes before any redesign. Run it first — `process-redesign` assumes it.

## Read the model before you ask

The operating model already holds the owners, the steps, the timings, the constraints, the
quality bars and the work in flight. **Ask the user only for what it doesn't have.**
Questioning someone about a process the model already describes wastes their time and
tells them you didn't look.

Where the model is missing something, that absence is usually the finding — say what isn't
recorded rather than quietly filling the gap from conversation.

## Sequence

1. **`kowalah_get_process`** with the process UUID. If you do not have the UUID, get it
   from `kowalah_get_operating_model_unit` (the unit's process list) or
   `kowalah_get_update`.
2. **Read the `diagnosis` block first** — before the steps, before the roll-up. It is the
   derived read of how well the process is actually captured, and it decides whether the
   rest of the data can be trusted.
3. **Check `access`** before offering to change anything.
4. Narrate the chain: steps in order, current→target dispositions, gap and constraint
   markers, the DEFINE contract on each step, and the ranked `backlog`.

## The counting rule that governs everything

**A null is "can't say". It is never "none".**

This is the single most important thing to get right, and the easiest to get wrong, because
a null renders as an absence and an absence reads as a clean bill of health.

- `handoff_count` is null whenever *any* step lacks an owner. A partial count would
  understate the handoffs — and the handoffs are where the waiting is. When it is null,
  say so and ask for the missing owners. Do not describe the process as though it flowed
  straight through.
- `cycle.ratio` is null unless *every* step is both timed and costed. A ratio built from
  three of twelve steps makes a process look tighter than it is.
- `touch_minutes_total` is a **floor**, not a total. Read it alongside
  `steps_missing_touch`. "At least 40 minutes, across the eight steps anyone has timed" is
  honest; "40 minutes" is not.

## Work is measured in minutes. Processes are measured in days.

`cycle.ratio` is touch time over elapsed time across the whole chain. **When it is there,
lead with it.**

A process that is 0.4% work and 99.6% waiting cannot be fixed by making the work faster.
That is usually the entire finding, and it reframes the conversation from "can AI do this
step quicker" to "why does this sit for six days between steps". Automating a step inside a
process that is 99% waiting moves nothing.

**When `cycle.ratio` is null, the missing timings are the finding.** Do not skip past it to
the parts you can measure. `cycle.steps_untimed` gives you the sentence: *"nine of twelve
steps have never been timed end to end — we cannot say where this process spends its
time, and that is the first thing to fix."* That is a more useful output than a confident
read of the three steps that happen to have data.

## The rest of the diagnosis block

- `constraint_steps` — steps marked as constraining the whole chain. These rank highest in
  the redesign backlog and are where effort actually pays.
- `steps_missing_output` and `steps_missing_acceptance_criteria` — the DEFINE contract
  gaps. A step with no defined output artifact or no acceptance criteria cannot be handed
  to AI, because there is no bar to hold it to. Route these to `quality-bar`.
- `steps_with_exception_notes` — where the documented process and the real one diverge.
  Worth reading aloud; exception notes are usually where the actual work happens.
- `chased_steps` — steps that need chasing. Chasing is coordination burden, and it is
  invisible in touch time.

## Use it to challenge, not just to report

The diagnosis is a set of questions to put to the owner, not a summary to read back. Good
challenges:

- "Four different people own steps in this chain. What happens between step 3 and step 4?"
- "Six of these steps have no acceptance criteria. How does anyone know when they're done
  right?"
- "The constraint is step 7, but the two initiatives aimed at this process both target
  step 2."
- "This is 12 minutes of work spread across 9 days. What are we actually trying to fix?"

## Before offering to change anything

`access` reports what this user may do to this process: `relationship`
(`at_own` / `below` / `at_peer` / `above` / `lateral`), `can_edit`, `can_create`,
`can_propose`.

**When `can_edit` is false, the route is `kowalah_propose_process_change`, not an edit that
will be refused.** Say which route you are taking and why — "this process is owned by
Operations, so I'll file this as a proposal for its owner rather than editing it" is a
useful sentence, not an apology.

`initiatives` lists the opportunities, deliverables and projects already aimed at this
process, pinned to a step where relevant. It is filtered to what this user may personally
see, so it can legitimately differ between colleagues — do not present it as the complete
list of work on this process.

## When an agent or tool runs a step

A step whose `platform_detail` names an agent or tool ("Brian drafts the reply", "the
Koko skill triages enquiries") but whose `implementations` are empty has the tool only in
free text. Offer to record it properly: `kowalah_get_ai_estate` to find the asset (or
`kowalah_record_ai_assets` to add it, if the user confirms it exists), with
`serves_step_ids` pointing at the step. Then the estate can say which steps depend on it,
and the step can say what runs it.

## What the process has delivered

`outcomes` lists the value recorded on the process and its steps, with `totals` per unit.
Claimed and verified are kept apart, and so are one-off and recurring. Read it alongside
the timings: a step that has had AI on it for months with no outcome recorded isn't a step
where nothing improved. Nobody has said what improved. Ask, and if the user knows, record
it (`outcomes` skill).

## Where to go next

- The process needs restructuring, not just better paint → `process-redesign`
- Steps lack acceptance criteria or quality checks → `quality-bar`
- Something needs to go to the Kowalah team → `raise-opportunity`
- Someone reports a saving or a win on this process → `outcomes`

View saved version →

---
name: process-redesign
description: Take a process from as-is to a proposed to-be — mark up what gets eliminated, merged or kept, then generate the redesign beside the original so the two can be compared. Use for "redesign this process", "how would we do this with AI", "these ten steps should be three", or when a diagnostic shows the process needs restructuring rather than automating.
---

# Process redesign

For a process owner who has diagnosed a process and concluded it needs restructuring. Run
`process-diagnostic` first — this skill assumes you have the diagnosis and have checked
`access`.

## Read the model before you ask

The operating model already holds the owners, the steps, the timings, the constraints, the
quality bars and the work in flight. **Ask the user only for what it doesn't have.**
Questioning someone about a process the model already describes wastes their time and
tells them you didn't look.

Where the model is missing something, that absence is usually the finding — say what isn't
recorded rather than quietly filling the gap from conversation.

## Why this is not a disposition change

A step's disposition — `human`, `ai_assisted`, `automated`, `ai_autonomous` — says **who
runs the step**. Every one of those values *keeps the step*.

Editing dispositions can only ever produce the same process with better paint. If the
answer is "these ten steps become three", no amount of disposition editing gets you there.
`kowalah_propose_redesign` is the tool that can.

So the first question is always: **is this a redesign, or is this automation?** If the
shape of the chain is right and individual steps should be run differently, use
`kowalah_save_process_step` to set target dispositions and stop. If the chain itself is
wrong, continue here.

## The order matters

**Mark up the real process first. Generate the redesign second.**

`kowalah_propose_redesign` *seeds* the to-be from the as-is and from the redesign decisions
already recorded on the steps. Call it before doing the thinking and you get a copy you
then have to prune by hand. Do the thinking first and you get a redesign that already
reflects it.

### 1. Mark each step

`kowalah_save_process_step` with the step `id`, setting `redesign_decision` and
`redesign_rationale`.

- Steps marked **`eliminate`** or **`merge`** do not carry across.
- Everything else carries.
- **A step with no decision is CARRIED, and reported back in `undecided_count`.** Silently
  dropping work nobody decided to drop would be the worst possible default — so an
  unmarked step survives. The count is your check that you covered the chain.

Always write `redesign_rationale`. The decision is what happens; the rationale is what
someone six weeks from now needs in order to argue with it. "Eliminate — this approval only
existed because the previous system couldn't enforce the limit" is defensible. "Eliminate"
alone is not.

Work through the chain in order and put a decision on every step, including the ones you
are keeping. An explicit "keep" and an unmarked step produce the same to-be but a very
different review.

### 2. Generate the to-be

`kowalah_propose_redesign` with the as-is `process_id`.

You get back a real process — status `draft`, `redesign_status` `proposed`, its own process
number — with `step_count`, `carried_count`, `dropped_count` and `undecided_count`.
**Nothing about the as-is changes.**

Check `undecided_count` immediately. If it is not zero, name the steps that carried without
a decision and ask whether that was intended.

## Two things are deliberately cleared on the to-be

Both are easy to read as bugs. Neither is.

**Target disposition is cleared.** The redesign is a new design question. Inheriting the
old target would pre-answer it — you would be deciding how to run step 4 of the new process
based on a judgement made about step 4 of a process that no longer exists.

**Elapsed time is cleared.** It is the number the redesign exists to *move*. Carrying it
over would make the comparison show a saving of zero until somebody noticed. The to-be
needs its own estimates, and putting them in is part of the design work — not an
afterthought.

Say both of these out loud when you present the redesign, or the first question you get
will be "why is the target column empty".

## Competing options are allowed and usually better

Call `kowalah_propose_redesign` twice and you get option A beside option B, both held
against the same as-is. This is often the right move: a conservative redesign and an
aggressive one, priced separately, lets the owner make a real decision instead of
approving or rejecting a single proposal.

To do this, set one pass of decisions, generate option A, then revise the decisions on the
as-is and generate option B. Name them clearly in the rationale so the two can be told
apart later.

## Presenting the comparison

Lead with the mechanism, not the count. "Ten steps to three" is a headline; *why* is the
argument:

- Which steps were eliminated and what made them unnecessary
- Which were merged and what handoff that removes
- What the constraint step becomes
- What the elapsed-time claim rests on — and flag it as an estimate, because the to-be's
  timings are exactly that until the process runs

If the as-is diagnosis had a `cycle.ratio`, frame the redesign against it. A redesign that
cuts touch time in a process that was 99% waiting has not fixed the problem, and it is
better to say that before someone else does.

## Permissions

Redesigning follows the same rule as editing: you may redesign a process you own or one at
or below your unit. Admins and core team may do it anywhere in the organisation.

Check the `access` block on `kowalah_get_process` first. **When `can_edit` is false, the
route is `kowalah_propose_process_change`** — it files an opportunity against the process
(optionally pinned to one step) so the owner can pick it up. Nothing about the process
changes. Anyone may propose against any process they can see, so this route is always open.

View saved version →

---
name: programme-review
description: Review the state of an AI operating model programme — coverage, where constraints concentrate, and whether the work in flight is aimed at the actual gaps. Use for "how is our AI programme going", "where are we with AI", "what should we do next", "prep me for the steering group", or any org-wide or divisional read of AI progress.
---

# Programme review

For the person accountable for AI across an organisation or a division: the AI programme
lead, the core team, the exec sponsor. The job is to say where the programme actually is
and what should happen next — not to recite a dashboard.

## Read the model before you ask

The operating model already holds the owners, the steps, the timings, the constraints, the
quality bars and the work in flight. **Ask the user only for what it doesn't have.**
Questioning someone about a process the model already describes wastes their time and
tells them you didn't look.

Where the model is missing something, that absence is usually the finding — say what isn't
recorded rather than quietly filling the gap from conversation.

## The one failure mode this skill exists to prevent

**A portfolio of initiatives aimed at places that had no gap.** It is the most common
finding and the least comfortable one. Coverage climbs, everyone reports green, and none
of the work is pointed at where the business is actually constrained. Every review must
end by testing the in-flight work against the gaps — not by reporting them on separate
slides.

## Sequence

1. **`kowalah_get_operating_model`** — the world view. Returns the unit tree with coverage
   roll-ups on every node, org-wide totals, and a `vision` block if one has been authored.
2. **Read the totals properly** (see below). Pick the two or three units where the
   constraints and redesign gaps actually concentrate.
3. **`kowalah_get_operating_model`** with `view: "rows"` — the whole model in one call:
   every unit with its subtree roll-up, every process with its `readiness`, the
   organisation's ranked redesign backlog (each item naming its process and unit) and the
   open questions. Read the units you picked from it, rather than opening them one at a
   time. If the connector doesn't accept `view: "rows"`, it's an older version: call
   `kowalah_get_operating_model_unit` on each of those units instead.
4. **`kowalah_get_update`** with no query — the portfolio of what is actually in flight:
   projects, deliverables, expert requests, opportunities, client-visible risks.
5. **Cross-reference.** For each significant in-flight item, name the unit and process it
   is aimed at. Then name the top-backlog items with nothing pointed at them.

Steps 4 and 5 are not optional. A review that stops at step 3 is a coverage report.

## Reading coverage honestly

**Coverage % is the vanity metric.** It says how much of the mapped business has processes
recorded against it. It says nothing about whether those processes are any good, whether
anyone is working on them, or whether the ones that matter are covered. Never lead with it.

**Lead with where constraints concentrate.** The roll-ups carry `constraint count` and
`redesign-gap count` across each unit's whole subtree. A unit at 80% coverage with fifteen
constraints is in worse shape than one at 40% with two. Say that plainly.

**Mind the denominator.** Roll-ups cover what has been *mapped*. A division with no
processes recorded shows no constraints — not because it has none, but because nobody has
looked. If a unit's process count is zero or near it, that absence is the finding. Do not
let an unmapped unit read as a healthy one.

**Coverage moving is not progress.** Mapping more processes raises coverage without
changing anything about how the business runs. Progress is constraints closing and
redesigns landing. If coverage rose and the constraint count did not fall, say so.

## Using the vision map

When a `vision` block comes back, it carries the vision statement, the guiding principles,
and the programme success measures — in the organisation's own words, from their AI Vision
Day.

Each principle has defining attributes as an assertion plus a counter-clause: *"It moves a
business KPI." / "Not a good idea in search of one."* **That pair is the test.** Apply both
halves. The counter-clause is the half that does the work — it is what lets you say a
piece of in-flight work is off-vision without it being an opinion.

Quote the principles in their own words. Do not paraphrase them into generic AI-strategy
language; the specific wording is the thing the organisation agreed to.

When `kowalah_get_operating_model_unit` returns a vision with `ownership: "inherited"`, say
whose it is — "you are working to the group vision, this division hasn't authored its own"
is itself a finding worth surfacing.

**Read the success measures as numbers where they have them.** From `kowalah_get_vision`,
each measure carries a numeric baseline, target and current reading, when these have been
set, and `progress` towards the target. The text baseline and target are the workshop's
words, so quote those. Report the numbers as progress. Check when the current reading was
taken (`currentMeasuredAt`): a measure with no current reading hasn't been read, which is
not the same as not having moved. Where outcomes have been recorded against a measure, the
`outcomes` skill can show what's behind the movement.

**Check `lastUpdatedAt` on the vision block, and say how old it is.** A vision is the
foundation every other judgement in this review rests on, so its age changes what the
review means. Coverage that doubled against principles nobody has revisited in a year is
not obviously progress — it may be a year of work aimed at last year's priorities. Put the
date in the review: *"these principles were last authored in March, and the portfolio has
turned over twice since."* If it looks stale, the next decision may be re-authoring the
vision rather than adding to the backlog.

## What a good review says

Four things, in this order:

1. **Where the business is constrained** — named units, named processes, with numbers.
2. **Whether the work in flight is aimed there** — the cross-reference from step 5, with
   both the hits and the misses.
3. **What is unmapped** — where you cannot say anything because nobody has looked.
4. **The next decision** — not a list of everything possible; the one or two things that
   would change the picture, and who has to decide.

Where the user wants to act on a gap, hand off to `raise-opportunity` rather than writing
the opportunity inline — it checks the accelerator library first and gets the ICE score and
vision test right.

## Scope and permissions

`kowalah_get_update` returns different things by role. Admins and core team see everything
in the organisation; members see only their own opportunities plus items they are a
stakeholder on. If the user is a member, the portfolio view is partial by design — say so
rather than presenting it as the whole picture.

If the user belongs to more than one Kowalah organisation, the model tools need an
`organization_id`. Call `kowalah_get_update` with no query first to list their
organisations, then ask which one — do not guess.

If either model tool returns `kind: "empty"`, no operating model or vision has been mapped
yet. That is Define-phase work their Kowalah team does with them; say that rather than
offering to map it from scratch here.

One thing to rule out first: a model showing **one unit and zero processes**, where the
user is the sole `admin` of a single organisation and no vision exists, is not an unmapped
client. A new organisation was created for this account instead of it joining the
company's existing one. That is the normal state for someone self-serving with no
engagement, in which case there is no programme to review yet and the useful offer is to
help them map one. It is the wrong place for someone whose company already works with
Kowalah. Judge the shape, not the name: a newly-created organisation is named from the
signer-up's email domain, so it can carry the company's own name and still be empty. See
the `kowalah-setup` skill.

View saved version →

---
name: programme-views
description: Design and build something the person can share about their AI programme — a dashboard, a slide deck, a document, a one-page visual or a short animated walkthrough — from their Kowalah operating model plus any other sources they choose. Works out who they are and who it's for, then designs it with them rather than filling a template. Use for "build our AI programme dashboard", "make me a board deck on our AI progress", "write up the steering group update", "I need something to show my team", "turn this review into slides", or any request to present the operating model to someone else.
---

# Programme views

Someone needs to show the AI programme to someone else: a steering group, a board, their
own team, a new joiner. This skill helps their AI assistant design and build that with them. It
is a design partner, not a template. The operating model is the backbone, and the person
decides what else goes in.

Three steps, in order. Don't start building until step 3 has an agreed outline.

## 1. Who they are, and who it's for

**Read before you ask.** Call `kowalah_get_update` with no query. It says who the person is,
their role in the organisation (admin, core team or member) and, where set, their home
unit. If they belong to more than one organisation, ask which one this is for.

Then ask the two questions the model can't answer:

- **Who is it for?** The reader matters more than the author. A board reads differently
  from a steering group, and a team reads differently from both.
- **What should the reader do or decide after seeing it?** A view with no decision behind
  it turns into a status report nobody acts on.

Their role suggests what they probably need. Use it as a first guess to check, never as a
box to put them in. An admin might run the programme or sponsor it, so ask which. Read the
matching guide in `references/roles/`:

| Usually | Guide |
|---|---|
| Runs the AI programme day to day | `references/roles/ai-programme-lead.md` |
| Sponsors it: accountable to the board or leadership team | `references/roles/executive-sponsor.md` |
| Owns a business process or function | `references/roles/process-owner.md` |
| Does the work in a process | `references/roles/team-member.md` |

## 2. What else they've got

The operating model holds processes, steps, coverage, the redesign backlog, open questions
and the vision. It doesn't hold everything a good view might need.

- **Look at what's connected.** Check which other tools are available in this conversation:
  a CRM, a data warehouse, a finance system, a document store. Suggest the ones that would
  add something real, such as pipeline value beside the sales processes or actual close
  dates beside the finance close. Say why each would help.
- **Use what's already known.** If memories or project files describe their priorities,
  their board's questions or a previous update, use them, and say that you did.
- **The person chooses.** Suggest, never pull in a source unasked. Some data shouldn't go
  in front of every reader, and they know which.

Keep a note of where each figure will come from. Every number in the finished piece has to
show its source.

## 3. Design it together, then build

**Agree the format.** Read the guide for the one that fits:

| Format | Good for | Guide |
|---|---|---|
| Dashboard | A view people come back to, with live figures | `references/formats/dashboard.md` |
| Slides | A meeting or a board pack; travels as a file | `references/formats/slides.md` |
| Doc | A written update people read, comment on and edit | `references/formats/doc.md` |
| Design | A one-page visual: a summary, a poster, a process on a page | `references/formats/design.md` |
| Motion | A short animated walkthrough of a process or a change | `references/formats/motion.md` |

Not every format is available everywhere. What you can make depends on the assistant
you're running in, the person's plan and what their administrator has switched on. In
Claude, each format is an artifact started from a template (a Dashboard, Slides, Docs,
Design or Motion artifact). Each guide says what to start from where a template exists,
and what to produce where it doesn't. If the format they want isn't available, say so and
offer the closest one that is.

If what they want fits none of these, build a single self-contained web page (in Claude,
an HTML artifact). The rules below still apply.

**Agree the outline before building.** Propose the sections, what each one shows and the
source of every figure. Let them change it. A piece built without this step is usually
built again.

**Then fetch and build.** `references/data.md` covers which call returns what, how to label
each figure and what isn't available.

## Rules for every view, whatever the format

1. **Lead with where the business is constrained, not with coverage.** Coverage says how
   much has been mapped. Constraints and redesign gaps say where work is actually stuck.
   Coverage belongs in the piece, not at the top of it.
2. **Label figures from `definitions`.** Every operating-model answer says what each figure
   means. Use that wording, so a figure means the same thing on every view.
3. **Name what isn't there.** If a figure can't be produced (because it isn't recorded, or
   the model doesn't hold it), say so on the page. A gap left out reads as a gap that
   doesn't exist. A cut list says how much was cut: "10 of 29 open questions".
4. **Steps, not people.** Describe constraints, handoffs and delays as steps in a process,
   never as named people or roles. Attach outcomes to the step or process they happened
   in. A view that reads as a judgement on individuals won't get honest data next time.
5. **Be careful with time saved.** Hours saved is a real result, but in front of a team it
   can be heard as a headcount number. Say what the time is going to, if the organisation
   has said. If it hasn't, report the hours and leave the interpretation to the people
   accountable for it.
6. **Show where every number came from.** Kowalah figures cite the operating model; other
   figures cite their own system. Mixed sources with no attribution can't be checked, and
   a number nobody can check stops being trusted.
7. **Say how old things are.** Note when the vision was last updated and when figures were
   read. A view people come back to should show the date of its data.

## Hand-offs

- If they want to find the gaps before presenting them, `programme-review` does the
  analysis and this skill presents it.
- If the view shows a gap worth acting on, hand off to `raise-opportunity`.
- To report value delivered in detail, use `outcomes` alongside this skill.

Referenced files: 10 — file references are metadata, not package contents.

View saved version →

---
name: quality-bar
description: Define what "good" means for a process step and set the checks that hold it there — acceptance criteria, gates and monitors, target scores. Use for "how do we know the AI is doing this right", "set up evals for this step", "what counts as a good output here", or before handing any step to AI.
---

# Quality bar

For a process owner who is about to let AI run part of a process, or who already has and
cannot say whether it is working. This is where a business owner sets the bar in their own
terms — *"what counts as a good forecast category call"*, *"what a compliant response looks
like"* — rather than delegating it to whoever builds the thing.

## Read the model before you ask

The operating model already holds the owners, the steps, the timings, the constraints, the
quality bars and the work in flight. **Ask the user only for what it doesn't have.**
Questioning someone about a process the model already describes wastes their time and
tells them you didn't look.

Where the model is missing something, that absence is usually the finding — say what isn't
recorded rather than quietly filling the gap from conversation.

## The rule this enforces

**A step with no acceptance criteria cannot be handed to AI, because there is no bar to
hold it to.** Not "should not" — cannot, meaningfully. You can wire it up, but you will
have no way to say whether it works, and no way to notice when it stops.

`kowalah_get_process` reports `steps_missing_acceptance_criteria` and
`steps_missing_output` in its `diagnosis` block. Those two counts are the backlog this
skill works through.

## Sequence

1. **`kowalah_get_process`** — read the steps, their DEFINE contract
   (`acceptance_criteria`, `input_artifact`, `output_artifact`), and any evals already
   attached. Check `access`.
2. **Fix the contract first** with `kowalah_save_process_step`. A step needs a defined
   `output_artifact` before an acceptance criterion means anything — you cannot say what
   good looks like until you have said what the thing *is*.
3. **Then attach evals** with `kowalah_save_process_step_eval`.

Doing 3 before 2 produces evals that check something nobody has defined.

## Writing acceptance criteria that work

The test of a criterion: **could two people independently apply it and agree?**

- *"The response is accurate and helpful"* — fails. Nothing to disagree with, nothing to
  check.
- *"Every figure quoted traces to a row in the source ledger, and no figure appears that
  isn't in it"* — passes. Checkable by anyone, and it names the failure mode that actually
  happens.

Write criteria against the **failure you are afraid of**, not the success you are hoping
for. Ask the owner: what would a bad output look like, and who would be harmed by it? That
question produces better criteria than "what does good look like" in about nine cases out
of ten.

## Gate or monitor

`mode` is the decision that matters most, and it is a business decision, not a technical
one.

- **`gate`** — blocks the step until it passes. All-or-nothing. It **must not** carry a
  `sampling_pct`; setting one is rejected, because a gate that only checks 20% of cases is
  not a gate.
- **`monitor`** — observes a sample and reports. May set `sampling_pct` (0–100).

Choose a gate when a single bad output is unacceptable — a payment released, a regulated
communication sent, a customer commitment made. Choose a monitor when you need to know the
error rate but individual errors are recoverable.

Most steps want both: a narrow gate on the thing that must never go wrong, plus a monitor
on overall quality. They are separate eval rows on the same step.

## The other eval fields

- **`method`** — `human_review` (default) | `llm_judge` | `programmatic` | `golden_set`.
  Start at `human_review` unless there is a reason not to; a human-reviewed eval that
  actually runs beats an automated one nobody built. `golden_set` is the strongest option
  where you have a set of known-correct cases to hold against.
- **`criteria`** — free text, what "pass" means. This is where the owner's own words go.
- **`target_score`** — the bar. **`current_score`** — the latest reading. Setting
  `current_score` stamps the measurement time automatically; clearing it clears the stamp.
  You cannot set the timestamp, the source, or the position — the server owns all three.
  **Read that stamp back and check its age.** A `current_score` measured eleven months ago
  is not a current score, and reporting it as one is how a step drifts for a year while the
  dashboard says it's passing. Quote the reading with its date, or say plainly that nobody
  has measured this since.
- **`status`** — `defined` (default) | `active` | `retired`. An eval sitting at `defined`
  is a written intention, not a running check. Be precise about the difference when
  reporting: "we have defined four evals and none are active" is the honest version.
- **`owner_user_id`** — the eval's owner on the client side. This matters: **once created,
  the eval's owner may edit it thereafter even if the process itself sits above their
  altitude.** So a function lead can own the quality bar on a process they do not otherwise
  control. Set it deliberately.

## Jidoka: autonomous steps need a stop-condition

When a step's effective `target_disposition` is **`ai_autonomous`**, an
`escalation_trigger` is **required** — the condition that returns control to a human. A
partial update that would leave the step autonomous without a trigger is rejected.

This is not a form field to fill in. Ask the owner directly: *what has to happen for a
person to be pulled back in?* Good triggers are specific and observable — a confidence
threshold, a value above a limit, a case type, an eval failing. "If something goes wrong"
is not a trigger.

If the owner cannot name one, that is a strong signal the step is not ready to be
autonomous. Say so, and set the target to `ai_assisted` instead.

## Permissions

Creating an eval needs edit rights on the parent process. If `access.can_edit` is false,
route through `kowalah_propose_process_change` — a proposal to add a quality gate is
exactly what that tool is for.

Once an eval exists, its `owner_user_id` may edit it regardless of process altitude. Admins
and core team may do either anywhere in the organisation.

View saved version →

---
name: raise-opportunity
description: Take an idea or an ask to the Kowalah team properly — check what already exists, test it against the AI vision, score it, and submit it. Use for "I need help with", "raise this with Kowalah", "we should look into", "I've got an idea about", or when a review turns up a gap somebody wants to act on.
---

# Raise an opportunity

`kowalah_create_opportunity` is the single entry point for everything a client might want
help with — a quick question, a piece of work for the Kowalah team, a new initiative, a
project to scope. **The user does not need to decide in advance which it is.** They
describe what they are trying to do; Kowalah triages from there. Anyone in the organisation
can raise one, at any role.

This skill is the four things to do before submitting. Skipping them is how thin,
unscoreable opportunities end up in the queue.

## Read the model before you ask

The operating model already holds the owners, the steps, the timings, the constraints, the
quality bars and the work in flight. **Ask the user only for what it doesn't have.**
Questioning someone about a process the model already describes wastes their time and
tells them you didn't look.

Where the model is missing something, that absence is usually the finding — say what isn't
recorded rather than quietly filling the gap from conversation.

## 1. Check the library first

**`kowalah_find_accelerator`** before anything else. The library holds proven skills,
plugins, prompts, guides and templates: the organisation's own accelerators plus Kowalah's
library, each result tagged with a `scope` of `organization` or `kowalah`.

Each result lists an edition per AI platform, with how to get it (download, read or
watch, open a link, copy a prompt), how to use it, and a `url` to its page in the Kowalah
app, where files are downloaded. If the ask is about a step in their operating model, pass
its `process_step_id` to find what fits that step. A result with `access: "preview"` is
one their plan shows only in outline: say what it does and pass on the note about the
full library, rather than guessing at its contents. **If there is a
match, the right outcome is the user using it today — not an opportunity raised for
something that already exists.** Say what you found, offer it, and only continue if it
genuinely does not fit.

Search on the problem, not the solution. Someone asking for "an AI tool to summarise
supplier contracts" should be searched as "contract review" and "supplier" separately —
the useful match is rarely phrased the way the ask is.

## 2. Get the description to something real

The server enforces a minimum length, but the bar that matters is higher than the one it
checks. A one-line opportunity wastes everyone's time and is slower to triage.

If the first message is thin, ask:

- What is the goal — what changes if this works?
- What would good look like?
- What context should Kowalah know that isn't obvious? Systems, constraints, who is
  involved, what has already been tried.

Write it up as a paragraph or more. Keep the user's own words for the goal; they are
usually more precise than a tidied-up version.

## 3. Test it against the vision

If the organisation has a vision map — the `vision` block on
`kowalah_get_operating_model`, or `kowalah_get_vision` — **name in the `content` which
guiding principle this serves and which KPI it moves.**

Several clients make this their own programme success measure: *every use case names the
KPI it moves before it starts.* This tool is where that gets enforced, so do it properly.

Each principle carries its defining attributes as an assertion plus a counter-clause — *"It
moves a business KPI." / "Not a good idea in search of one."* **Apply both halves.** The
counter-clause is the useful one; it is what lets you tell the user their idea is a good
idea in search of a problem without it being your opinion.

**If it does not obviously serve any principle, say so to the user before submitting. That
is a real signal, not a blocker.** Plenty of worthwhile work sits outside the current
vision, and surfacing the mismatch is more useful than quietly forcing a fit.

If `lastUpdatedAt` shows the vision map is well over a year old, note that alongside the
mismatch. "This doesn't fit the vision, but the vision hasn't been revisited since last
March" is a fairer thing to put in front of a triage team than either half alone.

Skip this step entirely when no vision map exists.

## 4. Score it

ICE — impact, confidence, ease, each 1–10, with a short rationale for each. Technically
optional in the schema; **expected in practice.** Unscored opportunities are slower to
triage and give the team nothing to weigh them against. Skip only if the user explicitly
declines.

For `impact`, use the slot that fits — the point is a number the business recognises:

- **business** — *"£2M annual cost reduction in supplier spend"*
- **productivity** — *"200 hours/week saved across support"*
- **adoption** — *"drive ChatGPT login rate from 15% to 60%"*

The composite is computed server-side. Partial scores are accepted, but push for all three
numbers plus a rationale each. Do not invent the numbers — ask. "What would this be worth
if it worked?" is a question the user can usually answer, and their answer is better than
your estimate.

## Before you call the tool

- **Which organisation?** `organization_id` is required. If the user belongs to more than
  one, ask — do not guess. `kowalah_get_update` with no query lists their organisations.
- **Is this a response to a Kowalah discovery?** Check `pending_discoveries` in the
  `kowalah_get_update` home view. If it is, pass that `discovery_id` — it links the
  response to the brief, stamps the opportunity with the discovery and its project, and
  marks the audience invite responded. Anchor the impact rationale to the discovery's
  `business_value_context`.
- **Is it about a process the user cannot edit?** Then the right tool is
  `kowalah_propose_process_change`, not this one — it files the opportunity against the
  process (optionally pinned to one step) so the owner can pick it up.
- **Optional but useful:** `department`, `source_note` (*"raised at yesterday's leadership
  meeting"*), `requested_project_id`.
- **`requested_target_type`** — `deliverable` or `expert_request` — only if the user has a
  strong view on the form of help. **Omit it if they are unsure.** Guessing here pre-empts
  a decision Kowalah makes together with the client, and a wrong guess is worse than no
  guess.

## After

**Tell the user the opportunity number.** It is how they refer back to it — `kowalah_get_update`
with that number brings up its status. The response also returns their recent opportunities,
so they can see their queue; worth showing if they have several in flight.

View saved version →

---
name: scheduled-tasks
description: Help someone set up a scheduled task in their AI assistant that brings them something useful from Kowalah on a regular basis — what's new in their accelerator library, a draft of their weekly programme update, the week in their area, progress against their vision, or ideas from their own work. Suggests ideas that fit their role, lets them choose, then writes the task. Use for "set me up a weekly update", "keep me posted on new accelerators", "can this run every Friday", "remind me each week", "automate my steering update", or "what could I schedule?".
---

# Scheduled tasks

A scheduled task is a prompt the person's assistant runs on a timetable, on its own: every
Monday morning, every Friday afternoon, the first of the month. Set up well, it brings
them something they'd otherwise have to remember to ask for. This skill suggests tasks
that fit them, lets them choose, and writes the task so it works without this
conversation.

**The person chooses and creates the task.** You suggest; they decide what runs, how
often and where the results go. Nothing is set up without their yes.

## 1. Who they are

Call `kowalah_get_update` with no query. It gives their role in the organisation (admin,
core team or member) and, where set, their home unit. If they belong to more than one
organisation, ask which one this is for.

Then ask, in one go:

- **What would they like to hear about, or stop doing by hand?** Their answer beats any
  suggestion.
- **When?** Which day and time suits them, and how often.
- **Where should the result go?** A message in their assistant is the default. If they
  have email, chat or a document store connected, they may want it there instead.

## 2. Suggest a few ideas

Read `references/ideas.md` and suggest two or three ideas that fit their role and what
they told you. Say in a sentence what each would give them, and let them pick one. One
good task they keep beats four they switch off.

Ideas fall into two kinds:

- **Ones that tell them something:** what's new in their library, the week in their area,
  progress against the vision. Read only. A good first task for anyone.
- **Ones that draft something for them:** their programme update, ideas from their own
  work. The task prepares a draft; the person reviews it and decides what happens next.

## 3. Write the task, then create it

Write the task prompt from the matching idea's template, filled in for this person. A
scheduled run starts fresh, with none of this conversation, so the prompt must stand on
its own:

- **Name the organisation and, if it applies, the unit**, by name, so the run doesn't
  have to ask.
- **Say what to call and how to read it**, including "use the date of the previous run as
  `since`; on the first run, use seven days ago".
- **Say exactly what to report and in what form,** including what to say when there's
  nothing new. A short "nothing new this week" is better than padding.
- **Include the rules below** that apply to the idea.

Show them the prompt, the timing and where the result goes. Change anything they want.
Then, once they say yes, ask the assistant to create a scheduled task with that prompt and
timing. If their assistant can't create scheduled tasks, or they'd rather do it
themselves, give them the prompt and timing to set it up in their assistant's settings.

## Rules for every scheduled task

1. **Nothing is shared or saved on its own.** A scheduled run reads and drafts. Anything
   that would be written to Kowalah (an opportunity, a process change, an outcome) is put
   to the person to approve, never submitted by the run.
2. **Report what was checked.** The "what's new" answer lists what it `covers`. Report
   those, and don't suggest anything else was looked at.
3. **Steps, not people.** When a task describes work, delays or constraints, it describes
   steps in a process, never named colleagues.
4. **Their own work stays theirs.** A task that looks at the person's own calendar or
   documents leaves personal items out, only suggests, and shows them everything before
   anything goes further.
5. **Quiet when there's nothing.** If nothing has changed, say so in a line and stop.

## Hand-offs

- To change or stop a task later, the person does it in their assistant's settings, or
  asks their assistant.
- If a run turns up something worth acting on, the person can pick it up with
  `raise-opportunity`, `process-diagnostic` or `programme-views` in a normal
  conversation.

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: spot-opportunities
description: Talk through your own work and find where AI could actually help — grounded in your organisation's AI vision and what already exists, not generic advice. Use for "where could AI help me", "what should I be using AI for", "I'm not sure what to automate", "help me think about my job", or when someone has been told to look for AI opportunities and doesn't know where to start.
---

# Spot opportunities in your own work

For anyone in a client organisation, whatever their role. Most people who install this
plugin have no formal position in the operating model — they were told "have a look at your
work and log anything worth doing". This is that conversation.

The job is to get from *"here's what I do all day"* to either **something they can use
today** or **one well-formed opportunity**. Not a list of twelve ideas.

## Read the model before you ask

The operating model already holds the owners, the steps, the timings, the constraints, the
quality bars and the work in flight. **Ask the user only for what it doesn't have.**
Questioning someone about a process the model already describes wastes their time and
tells them you didn't look.

Where the model is missing something, that absence is usually the finding — say what isn't
recorded rather than quietly filling the gap from conversation.

## Ground it first — this is what stops it being generic AI advice

Before asking anything about their work:

1. **`kowalah_get_vision`** — the organisation's AI vision map, in its own words: the vision
   statement, the guiding principles with their defining attributes, the success measures.
2. **`kowalah_get_operating_model`** — the unit tree. You are looking for one thing: **is
   their part of the business already mapped?** If it is, their work is probably already a
   process with steps and an owner, and the conversation is different.

Anyone can read both of these regardless of role. If either returns `kind: "empty"`, carry
on without it — just don't invent a vision that hasn't been written.

If the model comes back with **one unit and no processes**, and they are the sole `admin`
of a single organisation with no vision authored, the account is in a new organisation
created at sign-up rather than their company's existing one. Say so before going further,
because it means two different things. For someone starting fresh it is the normal state:
what they log is theirs, in their own organisation, and the conversation carries on. For
someone whose company already works with Kowalah it is the wrong place, and what they log
will not reach the colleagues they expect. Ask which it is. Don't be reassured by the
organisation's name — it is derived from their email domain, so it may well be their
employer's name. See the `kowalah-setup` skill.

Having the vision in hand changes the conversation from "what could AI do" to "what would
move the things we said mattered". Use the principles' own wording when you get to the
test; do not paraphrase them into generic AI-strategy language.

## Then talk about their actual work

Not a questionnaire. Ask what they do, then follow the friction.

**Their first answer will usually be a tool** — *"we should have a chatbot for this"*,
*"could AI write our reports"*. That is a solution, not a problem, and solutions offered
first are usually the ones that don't survive scrutiny. Take it, then go underneath it:
what makes the current way painful?

Questions that actually surface things:

- **What do you wait for?** Not what takes you time — what sits there while you can't move.
  Waiting is invisible on any time sheet and it is usually most of the elapsed time.
- **What do you redo?** Rework means something upstream isn't right.
- **What do you chase?** Chasing is pure coordination cost and nobody counts it.
- **Where do you copy between systems?** Re-keying is the most common real finding and
  almost nobody volunteers it — it feels too small to mention.
- **What's the bit you dread?** People are honest about this one, and dread usually tracks
  either high stakes or high tedium. Both are worth looking at.
- **What do you do that only you know how to do?** A single point of knowledge is a risk
  as well as an opportunity.

Follow one thread properly rather than collecting six. A specific, well-understood piece of
friction beats a broad wish every time.

## Check whether it already exists

**`kowalah_find_accelerator`** as soon as you have something concrete.

The library holds proven skills, plugins, prompts, guides and templates: the organisation's
own accelerators plus Kowalah's library, tagged `organization` or `kowalah`. Each result
lists an edition per AI platform (how to get it and how to use it), a security summary
(what it can read or do, and whether a person approves its actions) and a `url` to its page
in the Kowalah app. When you're looking at a particular step of their work, pass its
`process_step_id` to find what fits that step.

**If there's a match, the best possible outcome of this conversation is them using it
today.** That is a better result than a well-written opportunity, and it costs nothing.
Say what you found and offer it.

Search on the problem, not their proposed solution. Someone asking for "an AI tool to
summarise supplier contracts" should be searched as "contract review" and "supplier"
separately.

## Test it against the vision

If a vision map exists, apply it before going further.

Each principle carries its defining attributes as an assertion plus a counter-clause —
*"It moves a business KPI." / "Not a good idea in search of one."* **Both halves are the
test.** The counter-clause is the one that does the work: it lets you tell someone their
idea is a good idea in search of a problem without it being your opinion.

Glance at `lastUpdatedAt` before leaning on it hard. If the vision is a year or more old,
apply it as written but hold it more loosely — and if a good idea fails a stale principle,
that is worth saying out loud rather than using it to close the conversation.

Name the principle it serves and the KPI it moves. If it serves none, **say so** — plenty
of worthwhile work sits outside the current vision, and the mismatch is more useful
surfaced than quietly forced to fit.

## Where it goes

Three routes. Pick one; don't offer all three.

**They can use an accelerator today** → hand it over and stop. Done.

**It's about a process that's already in the operating model** → `kowalah_get_process` to
read it, then **`kowalah_propose_process_change`**. This files it against the process
(optionally pinned to one step) so the owner picks it up. Anyone may propose against any
process they can see, whatever their role, and nothing about the process changes. This is
the right route whenever the work is already mapped — it lands with the person who can
actually act on it.

**It's a new ask** → hand off to **`raise-opportunity`**, which gets the description, the
ICE score and the vision reference right. Don't write the opportunity inline here.

## Be straight with them

- **Don't promise anything gets built.** An opportunity is an ask that gets triaged by the
  Kowalah team, weighed against everything else. Say that.
- **"No opportunity here" is a fine outcome.** A conversation that ends with someone
  understanding their own process better and nothing logged is a success. Manufacturing an
  opportunity to have something to show wastes the triage queue and their time.
- **What they see is partial.** They can read the whole operating model and vision, but
  `kowalah_get_update` shows them only their own opportunities plus items they're a
  stakeholder on. If they ask what else is going on, that's the honest answer — there may
  be work in flight on this already that they can't see. Worth mentioning before they raise
  something.
- **Ask which organisation** if they belong to more than one. `kowalah_get_update` with no
  query lists them.