> ## Documentation Index
> Fetch the complete documentation index at: https://docs.akua.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Communication style
> How agents adapt explanations, vocabulary, and detail level to each user
Agents should feel like a senior colleague who knows when to explain and when to move quickly. A new developer should not have to understand Kubernetes vocabulary before deploying an app. A platform engineer should not have to read beginner explanations before getting to the diagnosis.
## Proficiency profiles
| Profile | Best for | How the agent speaks |
| ------------ | --------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| Beginner | Developers who have shipped code but not operated infrastructure | Everyday language, one step at a time, UI prompts before actions. |
| Intermediate | Developers who know containers and platforms like Vercel, Railway, or Heroku | Container-level vocabulary, short explanations for infrastructure terms. |
| Advanced | Backend engineers familiar with Docker, Kubernetes basics, logs, and deployment configuration | Correct Kubernetes terms, concise explanations, YAML or diffs when useful. |
| Expert | Platform engineers, SREs, and infrastructure teams | Direct technical detail, tradeoffs, raw resource names, and fewer confirmations for routine actions. |
Users should be able to change this at any time with a control such as **Talk to me as: Beginner / Intermediate / Advanced / Expert**. The agent should not silently change someone's level based on writing style.
Akua should remember the user's default per workspace. A session can override it for a single conversation, and the active style is stored on the session.
The profile changes presentation, not reasoning quality. The agent should still inspect the same logs, events, repository change requests, resources, and evidence. Beginner mode should put the plain-language summary first, while keeping technical details available. Expert mode should surface the technical detail immediately.
## Same issue, different language
Each example below describes the same diagnosis. Only the explanation changes; the underlying evidence stays the same.
```text theme={null}
Agent: Found it. Your app is trying to use a database, but no database is
connected yet.
I can set one up and connect it for you. It should take about a minute.
[Approval: Set up database] [Not now]
```
```text theme={null}
Agent: Your container exits because DATABASE_URL is missing. I can create a
Postgres instance and inject the connection string, or you can provide an
existing database URL.
[Create Postgres] [Use existing database]
```
```text theme={null}
Agent: Pod is in CrashLoopBackOff. Last log line:
Error: connect ECONNREFUSED 127.0.0.1:5432
The app expects Postgres on localhost, but no database runs in the pod.
Use a Secret-backed DATABASE_URL or deploy Postgres separately.
[Create repository change request]
```
```text theme={null}
Agent: CrashLoopBackOff caused by DB connection to 127.0.0.1:5432.
No sidecar or local Postgres present. Recommend Secret-backed DATABASE_URL
and readiness gate after migration check.
I can patch values and create a repository change request.
```
## Learning mode
Learning mode is separate from proficiency. When enabled, the agent adds short, expandable explanations for concepts the user has not seen before.
```text Example theme={null}
Agent: I’ll start your app on one of your servers.
Learn the technical term:
In Kubernetes, this is called scheduling a pod onto a node. A pod is the running
copy of your app, and a node is a server in your cluster.
```
Learning notes should not repeat forever. Once a user has seen a concept, the agent can move on and gradually use more precise vocabulary.
This creates a small memory surface: Akua needs to remember which concepts a user has seen in a workspace. That memory should be visible, editable, and removable like other user preferences. It should not be inferred from private writing style or used to silently change the user's selected profile.
## Vocabulary mapping
| Concept | Beginner | Intermediate | Advanced | Expert |
| ---------------- | ------------------------------- | ---------------------- | -------------------- | ---------------------------------- |
| Cluster | your group of servers | your cluster | cluster | cluster |
| Pod | your running app | your container | pod | pod |
| Deployment | your app | your deployment | Deployment | Deployment |
| Namespace | project space | namespace | namespace | namespace |
| Helm chart | app installer | app package | Helm chart | Helm chart |
| Secret | stored password | secret | Secret | Secret |
| Liveness probe | health check | health check | liveness probe | liveness probe |
| CrashLoopBackOff | your app keeps crashing | container restart loop | CrashLoopBackOff | CrashLoopBackOff |
| ImagePullBackOff | could not download your app | image pull error | ImagePullBackOff | ImagePullBackOff |
| Rollback | go back to the previous version | roll back | rollback to revision | shift traffic to previous revision |
## Related topics
See realistic deployment, investigation, and compute recommendation flows.
Set communication style, runtime policy, grants, and triggers.