audience-impact

# Audience Impact

When assessing a change, ask: **who is on the other end, and how fast does this reach them?**

This skill provides a mental model — not an exhaustive ledger. Use it to reason about which audiences a change affects, then load the catalog skills for detailed surface tracing when needed.

## How to use this skill

1. Identify which **roles** and **deployment modes** the change touches (see definitions below)
2. Look up the change type in the **impact propagation table** to see how fast and how visibly it reaches each audience
3. Flag any **silent** impacts explicitly — these slip through review most often
4. If deeper surface tracing is needed, **Load:** `product-surface-areas` (customer-facing) or `internal-surface-areas` (internal subsystems)
5. Use the **deliverables table** to determine what artifacts the change needs (changeset, docs, migration guide, etc.)

When multiple audiences are affected, address them in pipeline order: immediate impacts first (Contributor), then versioned impacts (Builder — changeset + migration guide), then deployed impacts (Platform User — QA), then infrastructure (Self-hosted — docs). This matches the natural merge → publish → deploy sequence.

## Two-axis model

Audiences decompose into two independent axes:

**Role** — who is the person?
**Deployment mode** — where does the system run?

These are orthogonal. A Builder can be cloud or self-hosted. A Platform User can be cloud or self-hosted. Assess each axis independently.

## Roles

### Contributor
Develops the framework source code. Clones the repo, runs `pnpm setup-dev`, writes and tests code, submits PRs. They interact with build tooling, CI/CD, test infrastructure, database migrations, git hooks, changesets, and dev scripts. Changes to internal tooling, schemas, or dev workflows reach them **immediately** — they're working in the repo.

Representative surfaces: turbo/biome config, vitest setup, drizzle migration workflow, GitHub Actions, pre-commit hooks, `.agents/skills/`, AGENTS.md.

### Builder
Builds agents using published packages. Runs `npx create-agents`, installs `@inkeep/agents-sdk` and related packages, codes against the SDK builder API, uses the CLI (`inkeep push/pull/dev`), reads docs, and references cookbook templates. They interact with published npm contracts, TypeScript types, config file schemas (`inkeep.config.ts`), API endpoints, and documentation. Changes reach them **at the next npm publish or docs deploy** — there's a version boundary between their code and ours.

Representative surfaces: SDK builder functions (`agent()`, `project()`, `functionTool()`), CLI commands and flags, `defineConfig()` schema, published type exports, AI SDK provider, MCP package, OpenAI-compatible chat API, cookbook templates, agents-docs content.

### Platform User
Configures agents through the visual builder (manage-ui) without writing code. Creates projects, configures agents and tools via forms, manages API keys, sets up integrations (Slack, GitHub), views traces, runs evaluations, and manages team members and roles. Changes reach them **at the next UI deploy** — they see whatever the dashboard ships.

Representative surfaces: agent builder canvas, project/agent/tool/credential forms, API key management, traces dashboard, evaluation UI, work-app integration setup, member/role management, login and onboarding flows.

## Deployment modes

### Cloud
Uses Inkeep's hosted platform. Auth via SSO/Auth0, credentials managed through Nango-hosted OAuth, services deployed on Vercel. No infrastructure to manage. The `PUBLIC_IS_INKEEP_CLOUD_DEPLOYMENT` flag gates cloud-specific behavior.

Representative surfaces: Auth0/SSO config, Nango-hosted OAuth flows, Vercel deployment pipeline, cloud onboarding/invitation flows, hosted API URLs.

### Self-hosted
Deploys via Docker on own infrastructure. Manages databases (Doltgres, Postgres, SpiceDB), env vars (60+), auth setup (Better Auth, JWT keys), observability (OTEL/SigNoz), and applies migrations. Changes to infrastructure config, Docker setup, or env var schemas affect self-hosters directly — they must act on them.

Representative surfaces: `docker-compose.yml`, `.env.example`, database migration scripts, SpiceDB schema, OTEL exporter config, deployment docs (AWS/Azure/GCP/Hetzner guides).

Self-hosted is a **modifier** — it adds infrastructure surfaces on top of whatever role the person has. A self-hosted Builder manages both SDK integration *and* Docker deployment. A self-hosted Platform User manages both the dashboard *and* the underlying infrastructure.

## Impact propagation

This is the primary decision aid. Given a change, how fast and how visibly does it reach each audience?

| Change type | Contributor | Builder | Platform User | Self-hosted modifier |
|---|---|---|---|---|
| Internal tooling (biome, turbo, CI, test infra) | Immediate | None | None | None |
| Database schema (`manage-schema.ts`, `runtime-schema.ts`) | Immediate (run `db:migrate`) | Next publish (if types change) | Next deploy (if UI affected) | Must run migrations |
| SDK/core API (exports, types, builder signatures) | Immediate (tests break) | **Next publish — potentially breaking** | Transitive (if UI consumes affected API) | Transitive (if UI consumes affected API) |
| CLI commands or config schema | None | **Next publish — potentially breaking** | None | None |
| Manage UI (pages, forms, components) | None | None | **Next deploy — visible immediately** | Next deploy |
| API routes or response shapes | Immediate (snapshot tests) | **Next publish — potentially breaking** | Next deploy (if UI consumes it) | Next deploy |
| Validation schemas (Zod rules, allowed values, defaults) | Immediate (tests) | **Silent — previously valid input rejected** | **Silent — forms may fail unexpectedly** | **Silent — API calls may fail** |
| Docker/env config | Immediate (local dev) | None | None | **Immediate — must reconfigure** |
| Env var semantics (same name, changed meaning/format) | Immediate (local dev) | None | None | **Silent — system may behave incorrectly** |
| Documentation content | None | **Next docs deploy — may mislead** | Next docs deploy | Next docs deploy |
| Auth/permissions (RBAC, cookies, tokens) | Immediate (tests) | Next publish (if SDK auth changes) | **Next deploy — login/access may break** | Must update auth config |
| Telemetry contracts (span names, OTEL attributes) | Immediate (if tests assert spans) | None | None | **Silent — dashboards/alerts may break** |
| Trigger/webhook contracts (schemas, signatures, payloads) | Immediate (tests) | **Next publish — potentially breaking** | **Next deploy — trigger config may break** | Next deploy |

**Impact latency key:**
- **Immediate**: affects them in their current working session
- **Next publish**: affects them when they `npm update` — version boundary provides a buffer
- **Next deploy**: affects them when the UI/API redeploys — no version boundary, but there's a deploy gate
- **Transitive**: not directly affected, but may be affected if a downstream surface they use consumes the changed surface
- **Silent**: affects them without obvious signal — **most dangerous**. The system appears to work but behaves incorrectly (e.g., a validation change that silently rejects previously valid input, a telemetry contract change that breaks downstream dashboards)

## What counts as "breaking" per role

- **Contributor**: CI fails, tests break, dev setup stops working. Loud and immediate — usually caught before merge.
- **Builder**: Published API changes (removed exports, changed type shapes, new required config fields, altered CLI flags). Versioned via semver + changesets, but breaking changes in patch versions are especially harmful.
- **Platform User**: UI behavior changes (forms that worked differently, removed features, changed navigation). No version boundary — they experience it the moment it deploys.
- **Self-hosted**: Infrastructure contract changes (new required env vars, changed Docker config, new database migration steps). Silent if not documented — the system may appear to work but behave incorrectly.

## Deeper surface tracing

This skill tells you **who cares**. For detailed surface enumeration, load the catalog skills:

- **Load:** `product-surface-areas` — customer-facing surfaces (APIs, SDKs, CLI, UI, docs, templates). Maps primarily to Builder and Platform User roles.
- **Load:** `internal-surface-areas` — internal subsystems (build, CI, test, DB, auth, runtime). Maps primarily to Contributor role and the self-hosted modifier.

## Deciding what deliverables a change needs

| Affected audience | Likely deliverables |
|---|---|
| Contributor | Update/add tests. Update AGENTS.md if workflow changes. Update skills if conventions change. |
| Builder | Changeset (semver). Docs update. Migration guide if breaking. |
| Platform User | QA the UI change. Update visual-builder docs if behavior changes. |
| Self-hosted | Update `.env.example`. Update deployment docs. Migration guide if infra changes. |
| Cloud-only | Verify feature flag gating. Update cloud-specific onboarding if affected. |