> For the complete documentation index, see [llms.txt](https://docs.digit.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.digit.org/complaints-management/deploy/operations-handbook/l1-first-response.md).

# L1 - First Response

**For:** the service desk. The person who takes the call from a clerk, a supervisor or a citizen.

**Your job in one line:** work the checklist below; resolve it if it's on the [known-issues list](/complaints-management/deploy/operations-handbook/known-issues.md), and if it is not, hand L2 a filled-in Part A of the [incident report](/complaints-management/deploy/operations-handbook/incident-report.md).

**Not your job:** working out *why*. If you find yourself forming a theory about the cause, that is the L2's work — capture what you've found and pass it on.

**This page is only half of L1.** The other half is *requests* rather than faults — creating a user, adding a department or a complaint type, loading master data. Those are all done through the product's own admin screens, and they are yours, not L2s; the rule is [**if there is a screen for it, it is L1**](/complaints-management/deploy/operations-handbook.md#who-does-what-l1-vs-l2). This page covers the fault half.

You do all of this from a web browser. You never touch the server, and **nothing in this checklist changes anything** — every step is looking, not changing. You cannot break the system by following this page.

## Before You Start

### Logins and Passwords

**The health dashboard needs no login.** Open the URL, and you are in.

**Grafana does need one**, and you should have it *before* your first call rather than hunting for it during one. You do not use the `admin` login for this — that one belongs to your **system administrator**, and a new deployment has no other accounts. Grafana does not let people sign themselves up, so **the administrator creates a Grafana account for each L1 and L2 person**. Ask them for yours, and ask for two specific things:

1. **A named account of your own** — your username, not the shared `admin` login.
2. **The Editor role.** New accounts are created as **Viewer** by default, and a Viewer cannot open **Explore** — which [Step 4](/complaints-management/deploy/operations-handbook/l1-first-response.md#what-does-the-log-say) needs. If Step 4 shows you no Explore item in the left menu, this is why: go back and ask for Editor.

Editor cannot add users or change passwords, and nothing in this checklist changes the system — Grafana only displays data. Steps 3 and 4 below both need the login.

Everything else, ask your **system administrator** for:

<table><thead><tr><th width="339.8515625">If you need</th><th>Ask your system administrator</th></tr></thead><tbody><tr><td><strong>A Grafana account of your own</strong>, with the <strong>Editor</strong> role</td><td>Needed for Steps 3 and 4. Ask before your first call — the admin creates it for you</td></tr><tr><td>A password prompt appears where you did not expect one</td><td>They'll tell you the right URL, or add you to the VPN</td></tr><tr><td>The <strong>Novu</strong> notification dashboard (to see if a message was sent)</td><td>Access is not part of the service desk by default</td></tr><tr><td>The <strong>SMS / WhatsApp provider console</strong> (to check credit or credentials)</td><td>Usually held by whoever owns the provider contract</td></tr><tr><td>Access to the <strong>server itself</strong></td><td>That is L2's, not yours — you never need it for this checklist</td></tr></tbody></table>

**Never put a password, API key or token in a ticket**, even if someone asks you to. If you think a credential is part of the problem, say *which* credential, not what it is.

#### The two pages, and what they are

Bookmark these two. **They are the only URLs on this page** — after this, everything is described as menu clicks, so you don't have to memorise addresses.

<table><thead><tr><th width="117.81640625">Page</th><th width="231.7421875">URL</th><th>What it is</th></tr></thead><tbody><tr><td><strong>Health dashboard</strong></td><td><code>https://&#x3C;your-domain>/status/</code></td><td>A page that automatically tries up to 57 parts of the system every 30 seconds and colours each one green or red</td></tr><tr><td><strong>Grafana</strong></td><td><code>https://&#x3C;your-domain>/grafana/</code></td><td>The system's own recordings — memory, errors, logs — shown as charts and lists. <strong>Asks for a login</strong></td></tr></tbody></table>

**About Grafana**, because it looks intimidating the first time: it is a *viewer*. It reads recordings the system already made and draws them on screen. It does not control the system, and clicking around in it cannot start, stop or change anything. Explore it freely.

#### The nine dashboards, and the two that are yours

Grafana's **Dashboards** menu lists nine pages. **This checklist uses two of them**, and the other seven are L2's. That is not a restriction on you — it is which questions belong to which tier.

<table><thead><tr><th width="387.90234375">Dashboard</th><th width="221.6171875">Used in</th><th>Whose</th></tr></thead><tbody><tr><td><strong>DIGIT JVM Services</strong></td><td><a href="/complaints-management/deploy/operations-handbook/l1-first-response.md#did-something-crash-or-run-out-of-memory">Step 3</a> — two panels only</td><td><strong>Yours</strong></td></tr><tr><td><strong>DIGIT — Logs (Loki)</strong></td><td><a href="#what-does-the-log-say">Step 4</a></td><td><strong>Yours</strong></td></tr><tr><td>Node Exporter Full, PostgreSQL Database, Kong API Gateway, Redpanda (Kafka) Broker, DIGIT Kafka Consumer Lag, DIGIT — Traces (Tempo), DIGIT — CMS Analytics Queries</td><td>—</td><td>L2's</td></tr></tbody></table>

The seven answer *why* something is failing — is the database the bottleneck, is it the gateway or the service behind it, which pipeline is stuck. Reading them correctly needs to know what normal looks like on this deployment, and [working out why is not your job](#before-you-start). Looking at them cannot break anything, so look if you are curious — just don't put conclusions from them in a ticket.

**One exception worth knowing:** if a caller reports something that sounds like *"everything is slow"* or you see the words **"no space left on device"** anywhere, say so explicitly in the handover. Those two point L2 straight at a specific dashboard, and naming the symptom in those words saves them a step.

What every dashboard shows, if you want to read ahead: [**dashboards**](/complaints-management/deploy/operations-handbook/the-grafana-dashboards.md).

#### What you need before your first call

Check you actually have these, and ask L2 for anything missing. Each one is assumed by a step below.

<table><thead><tr><th>You need</th><th width="161.25">Used in</th><th>If you don't have it</th></tr></thead><tbody><tr><td>The two URLs above, reachable from your desk</td><td>Steps 2–4</td><td>Ask L2 — Grafana may sit behind the VPN</td></tr><tr><td>Your <strong>Grafana account</strong> (Editor role)</td><td>Steps 3–4</td><td>Ask your system administrator — they create it. Without it you can do Steps 0–2 and must hand over there</td></tr><tr><td>To know this deployment's <strong>observability level</strong></td><td>Step 4</td><td>Ask L2. On a <code>metrics</code>-level deployment there are no logs to read — see Step 4</td></tr><tr><td>A <strong>login of your own</strong> for the system</td><td>Step 1</td><td>You cannot confirm scope; say so in the ticket rather than guessing</td></tr><tr><td>A <strong>second test login</strong>, ideally in a different office</td><td>Step 1</td><td>Ask a colleague to try instead, and note whose account was used</td></tr><tr><td>The <strong>maintenance window</strong>, written on your <a href="/complaints-management/deploy/operations-handbook/cheat-sheet.md">cheat sheet</a></td><td>Step 3</td><td>Ask L2 before reporting restarts</td></tr></tbody></table>

An admin login to the Configurator or HRMS is **not** assumed anywhere on this page — the fault checklist is read-only throughout. You should still have one, because the request half of L1 (creating users, editing master data) is done entirely through those screens, and some entries in [known-issues ](/complaints-management/deploy/operations-handbook/known-issues.md)need one too. If you don't have one yet, ask your system administrator for it; until then, those items are for L2.

## **Steps**

{% stepper %}
{% step %}

### Note the details

Ask for these while the caller is still on the line. Going back for them later is the main reason a ticket stalls.

| Ask                                                                 | Why it matters                               |
| ------------------------------------------------------------------- | -------------------------------------------- |
| **What exactly were you doing?** The screen, the button, the action | Narrows it to one service                    |
| **What happened instead?** The exact message on screen              | Often names the failure outright             |
| **When did it start?** Date, time, timezone                         | Everything downstream is a time-range search |
| **Is it still happening right now?**                                | Decides whether evidence is still live       |
| **Which city / office / login?**                                    | Tenant and role scope                        |
| **Complaint number**, if there is one                               | Lets any tier trace it end to end            |

If the caller can send a screenshot, ask for one **with the error visible**.
{% endstep %}

{% step %}

### Is it just this one person?

Before opening any dashboard, find out whether this is one person's machine or the whole system. This costs a minute and decides everything that follows.

1. **Open the site yourself, in a private/incognito window**, and try the same action. This one test is the important one, and it needs nothing but your own login.
2. If you can, also vary **the account** (a second test login, or ask a colleague in another office to try) and **the network** (a phone hotspot).

#### What the result means, and what to do

<table><thead><tr><th width="187.83984375">Result</th><th width="199.92578125">What it means</th><th>Do this</th></tr></thead><tbody><tr><td>Works for you, fails for them</td><td>Their browser, network or account</td><td>Try the browser-side items in  <a href="/complaints-management/deploy/operations-handbook/known-issues.md">known-issues</a></td></tr><tr><td>Fails for you too</td><td>Server-side</td><td>Continue to Step 2</td></tr><tr><td>You can't test it yourself</td><td>Unknown scope</td><td>Say so explicitly in the ticket — "could not reproduce, no second account" is information; silence reads as "not checked"</td></tr></tbody></table>

**If you can reproduce it, capture the failing request while you're there** — it is the single most useful attachment and the caller cannot get it for you. Press **F12** → the **Network** tab → repeat the action → click the red row → screenshot the **URL and status code**. If you cannot reproduce it, skip this; do not talk a caller through developer tools on the phone.

Skipping this step is the most common way a single stale login turns into a system-wide alarm.
{% endstep %}

{% step %}

### Is everything up?

#### What this page is

The **health dashboard** is a page that tries every part of the system — up to 57 checks, though most deployments run somewhat fewer — every 30 seconds, and shows each result as a coloured tile. Green means that part answered. Red means it did not. You don't run anything — the page is already doing it continuously, and you're reading the latest result.

#### How to get there

Open the health dashboard URL from [Before you start](#before-you-start). There is nothing to click — the tiles are the page.

#### What you're looking at

Tiles are grouped by what part of the system they belong to. Scan for **any red tile**, and note its **exact name and group**.

{% hint style="info" %}
**Screenshot anything red immediately, before you do anything else.** This page keeps no history — it only knows the last few minutes. If the page reloads or the service recovers, the red is gone for good and cannot be recovered by anyone, including L2.
{% endhint %}

#### What each group means

<table><thead><tr><th width="183.80078125">Group is red</th><th>What's affected</th></tr></thead><tbody><tr><td><strong>Infrastructure</strong></td><td>The database, cache or message queue. Nothing else can work without these — this is the most serious thing on the page</td></tr><tr><td><strong>Core Services</strong></td><td>A shared platform service. Expect several unrelated-looking symptoms at once</td></tr><tr><td><strong>API Gateway</strong></td><td>The traffic director. Requests can't be routed; users see "502" or a blank screen</td></tr><tr><td><strong>Application</strong></td><td>The complaint system itself</td></tr><tr><td><strong>Search</strong></td><td>Inbox and search break; filing complaints still works</td></tr><tr><td><strong>Notifications</strong></td><td>SMS / email / WhatsApp not going out; everything else fine</td></tr><tr><td><strong>Sign-in / identity</strong></td><td>People cannot log in</td></tr><tr><td><strong>OTP</strong></td><td>One-time passcodes for login aren't being delivered</td></tr><tr><td><strong>MCP</strong></td><td>Integration tooling. No effect on citizens or staff using the system</td></tr><tr><td><strong>API Tests</strong></td><td>See below — this one means something different</td></tr></tbody></table>

#### Two things that confuse people

**The API Tests group is not like the others.** Every other group asks a service *"are you alive?"* — the service replies, the tile goes green. The API Tests group instead makes a **real request**, the same kind the application makes: searching for a city, generating a complaint number, fetching a translated message. So it proves the service can actually do its job, not just that it's running.

That means a **green service tile with a red API Tests tile is not a contradiction** — it tells you the service is alive but not working, which is usually a data or configuration problem rather than a crash. Note it and pass it on; it points L2 somewhere quite different.

**PostgreSQL and PgBouncer are listed separately on purpose.** PgBouncer sits in front of the database. It can keep answering happily while the database behind it is dead. If PgBouncer is green and PostgreSQL is red, treat it as **Infrastructure red**.

#### What to do about it

<table><thead><tr><th width="265.609375">What you see</th><th>Do this</th></tr></thead><tbody><tr><td><strong>Any Infrastructure tile red</strong></td><td><strong>Screenshot it and escalate immediately.</strong> Do not continue the checklist — nothing above the database can be trusted, and the remaining steps will just be noise</td></tr><tr><td>Any other red tile</td><td>Screenshot, write down the exact tile names, continue to Step 3</td></tr><tr><td>An API Tests tile red, service tiles green</td><td>Note it explicitly as "alive but API failing", continue to Step 3</td></tr><tr><td>Everything green</td><td>The parts are all running, so the problem is inside one of them or in the data. Continue to Step 3</td></tr></tbody></table>

**Record the exact names of the red tiles.** That list is most of what L2 needs.
{% endstep %}

{% step %}

### Did something crash or run out of memory?

#### What you're checking, and the words for it

Most of this system is written in Java. Every Java service is given a fixed amount of memory to work in — that allowance is called the **heap**. If a service needs more than its heap allows, it cannot continue and fails with an error called **OOM**, short for *out of memory*. When a service fails this way, it usually **restarts** — it stops and starts again from scratch, which takes it out of service for a minute or two.

You are checking two things, and only reading numbers:

* **Did anything run out of memory?**
* **Is anything restarting over and over?**

#### a. Out-of-memory count

**How to get there:** open **Grafana** → in the left menu click **Dashboards** → open **DIGIT JVM Services**.

**Set the time window first.** At the **top right,** there is a time control — it usually says something like *Last 6 hours*.

[![The time range control at the top right of every dashboard, reading "Last 6 hours"](https://github.com/egovernments/Citizen-Complaint-Resolution-System/raw/master/docs/operations/images/10-time-range-control.png)](https://github.com/egovernments/Citizen-Complaint-Resolution-System/blob/master/docs/operations/images/10-time-range-control.png)&#x20;

Everything on the screen is only about that window, so if you set it wrong you will see nothing and think all is well. Set it to **Last 6 hours**, or wider if the caller says the problem started earlier.

Now find the panel called **"OOM events (current range)"**. It is a **stat panel**, meaning it shows one single large number — the count of out-of-memory failures inside the time window you chose.

<table><thead><tr><th width="171.46875">Reading</th><th>What it means</th></tr></thead><tbody><tr><td><strong>0</strong></td><td>Normal. Nothing ran out of memory in that window</td></tr><tr><td><strong>Anything above 0</strong></td><td><strong>Check the panel below before treating it as a finding</strong> — see the next paragraph</td></tr></tbody></table>

If it is above zero, look at the panel directly below it, **"Incidents — OOM / heap-space errors"**. That lists the actual error lines and names the service.

[![The OOM events panel reading 116 in red — on this deployment every one of them was an echo, not a crash](https://github.com/egovernments/Citizen-Complaint-Resolution-System/raw/master/docs/operations/images/20-oom-events-echo.png)](https://github.com/egovernments/Citizen-Complaint-Resolution-System/blob/master/docs/operations/images/20-oom-events-echo.png)

*The panel above was photographed on a healthy deployment. All 116 were Grafana and Loki echoing a search back into the log — there had been no crash at all. Read the next paragraph before acting on a number like this.*

{% hint style="info" %}
**Check the service name before you escalate — this number has a known blind spot.** Grafana and Loki are the monitoring tools themselves, and they write your *search text* back into the log as an ordinary log line. So whenever anyone searches for the words "OutOfMemoryError", this panel counts that search as though it were a crash. On a deployment where L2 has been investigating, the number can read in the **hundreds** while nothing has actually crashed.

**How to tell in five seconds:** in the "Incidents" panel below, look at the service each line came from. If every line is from **`grafana`** or **`loki`**, there were **no real out-of-memory events** — record it as `OOM events: 0 (all grafana/loki echo)` and move on. Only lines naming an actual DIGIT service — `pgr-services`, `egov-indexer`, `egov-user` and so on — are real.
{% endhint %}

**What to do about it:**

{% hint style="info" %}
If **OOM events is above 0** — copy the error lines from the panel below it, note the **service name** and the **time**, and **escalate to L2**. Do not try to fix it. Do not restart anything. Fixing an out-of-memory usually means giving the service a bigger allowance, which is a deployment change and not something the service desk can or should do.
{% endhint %}

#### b. Restarts

**How to get there:** in Grafana's left menu, click **Explore**. At the top of the Explore screen, there is a datasource dropdown — choose **Loki** from it.

Then copy this line into the query box and press **Run query** (or Shift+Enter). You don't need to understand it — it is a search filter, and it's the same every time:

```
{compose_project="digit", compose_service!="loki"} |~ `Started .+Application in`
```

Every Java service writes one line when it starts up. This search finds those lines, so **each result is one service starting**. Widen the time range at the top right to **Last 24 hours**.

<table><thead><tr><th width="303.82421875">Reading</th><th>What it means</th></tr></thead><tbody><tr><td>A cluster of many services all starting at the same time</td><td>Normal, if that time is your maintenance window — the whole system was redeployed</td></tr><tr><td>The <strong>same service</strong> appearing over and over through the day</td><td>Not normal. That service is failing and restarting repeatedly</td></tr><tr><td>Nothing at all</td><td>Nothing restarted in that window. Also a useful finding</td></tr></tbody></table>

{% hint style="info" %}
**Check the maintenance window before you report restarts.** If this deployment redeploys on a schedule, every service restarts then and this query fills with normal activity. The window should be written on your [cheat sheet](https://github.com/egovernments/Citizen-Complaint-Resolution-System/blob/master/docs/operations/cheatsheet.md) — restarts *outside* it are the interesting ones. If that blank has never been filled in, ask L2 what the window is before treating restarts as a finding.
{% endhint %}

**What to do about it:**

{% hint style="info" %}
If the **same service keeps appearing** outside the maintenance window — copy the list of times, note the service name, and **escalate to L2** with the words **"possible restart loop"**. That phrase tells L2 exactly where to start. Do not restart anything yourself.
{% endhint %}

#### Record it, don't conclude from it

`OOM events: 3 — egov-indexer, 09:12` is the right note. "The system crashed because it ran out of memory" is not.

The out-of-memory may be a *consequence* of the real fault, or unrelated to what the caller reported. Say what you saw rather than what it means — in the ticket, and to the caller.

The other panels on that dashboard — the heap graphs and the right-sizing table — are L2's work ([L2-diagnosis](/complaints-management/deploy/operations-handbook/l2-diagnosis.md)). Reading them correctly means knowing what normal looks like for each service, and a normal memory pattern looks alarming until you've seen a few. Leave them alone.
{% endstep %}

{% step %}

### What does the log say?

#### What a log is

Every part of the system writes a running diary of what it is doing — each thing it starts, finishes, or fails at, with a timestamp. That diary is the **log**. When something breaks, the log usually says so in plain words, and that sentence is the single most useful thing you can put in a ticket.

Logs are kept for **72 hours**, so a problem from last week has no log left. This is why reporting quickly matters.

{% hint style="info" %}
**First check this step applies to your deployment.** Searchable logs come from a component called Loki, and some deployments are configured without it to save memory and disk — see [How much monitoring this deployment runs](/complaints-management/deploy/operations-handbook.md#monitoring-scope). If **DIGIT — Logs (Loki)** is not in the dashboard list at all, that is a deployment decision and **not a fault**. Skip to [Step 5,](/complaints-management/deploy/operations-handbook/l1-first-response.md#resolve-or-escalate) and write in the ticket: *"no log search on this deployment"* — L2 can still read logs on the server itself. Ask L2 once which level you are on and note it on your [cheat sheet](/complaints-management/deploy/operations-handbook/cheat-sheet.md), so nobody rediscovers this mid-incident.
{% endhint %}

#### How to get there

Open **Grafana** → left menu **Dashboards** → open **DIGIT — Logs (Loki)**.

**You do not need to write a query here.** This dashboard has three dropdowns across the top; set them and the logs appear underneath.

<table><thead><tr><th width="183.25390625">Control</th><th>Set it to</th></tr></thead><tbody><tr><td><strong>Service</strong></td><td>The service you suspect, from Step 2 or Step 3. If you have no suspect, leave it as <code>.+</code>, which means "all of them"</td></tr><tr><td><strong>Level</strong></td><td><code>ERROR</code> — this hides routine chatter and shows only failures</td></tr><tr><td><strong>Search regex</strong></td><td>Leave empty. Or paste a complaint number here to follow one specific case through the system</td></tr></tbody></table>

Then set the **time range** (top right) to **start ten minutes before the problem began**. Not when the caller rang — when it started. Failures cascade, and you want to catch the first one.

#### What you're looking at, and what to do

**Copy the oldest error you can see, not the newest.** When something breaks, other things fail after it in a chain. The first error is the cause; the rest are consequences. Scroll to the *bottom* of the list, which is the earliest entry in your window.

<table><thead><tr><th width="190.609375">What you see</th><th>Do this</th></tr></thead><tbody><tr><td>Errors are present</td><td>Copy the <strong>oldest</strong> one, with <strong>10–20 lines around it</strong>, as text. Note the service and the exact time range you used. <strong>Escalate to L2</strong></td></tr><tr><td>No errors at all</td><td>This is a real finding, not a dead end. Write it down explicitly: <em>"no ERROR lines between 09:00 and 09:30 for all services"</em>. It rules out a great deal for L2</td></tr></tbody></table>

Copy the text, not a photograph of the screen — text can be searched; a screenshot cannot.
{% endstep %}

{% step %}

### Resolve or escalate

**Check** [**known issues**](/complaints-management/deploy/operations-handbook/known-issues.md) **first.** If your symptom is in that table and the resolution is marked as one you're able to apply, do it and close the ticket, adding a line to the incident log.

Otherwise, escalate to L2 with **Part A** of the [incident report ](/complaints-management/deploy/operations-handbook/incident-report.md)filled in. Part A is exactly what you gathered above, so it should be a copy-paste job.

#### Escalate immediately, without finishing the checklist

Stop and hand over right away if any of these are true:

* **An Infrastructure tile is red** on the health dashboard.
* **Nobody can log in**, or the site doesn't load at all.
* **No complaint can be filed** by anyone.
* **A disk-full or "no space left on device" message** appears anywhere.

For those, do Step 2 (screenshot the red tiles) and hand over. The remaining steps can be done by L2 while you're notifying people.

#### And if everything looked normal

Say so, clearly. *"All health tiles green, OOM events 0, no restarts outside the maintenance window, no ERROR lines between 09:00 and 09:30"* is a genuinely valuable ticket — it rules out most of what L2 would otherwise spend an hour checking. An empty checklist reads as "nobody looked"; a filled-in one that found nothing reads as "we know where it isn't".
{% endstep %}
{% endstepper %}

<figure><img src="https://github.com/egovernments/Citizen-Complaint-Resolution-System/raw/master/docs/operations/images/30-logs-controls.png" alt=""><figcaption></figcaption></figure>

## Important Captures

Attach these to every ticket you pass on. Text, not photographs of a screen — text can be searched.

* [x] &#x20;The answers from **Step 0**
* [x] &#x20;**Scope** — did it fail for you too, in a private window, on another account?
* [x] &#x20;**Health dashboard screenshot**, if anything was red
* [x] &#x20;Any **red tile names**
* [x] &#x20;**Restart / OOM findings** from Step 3, with times
* [x] &#x20;The **error text** from Step 4, plus the time range and service you used
* [x] &#x20;The **complaint number/user ID**, if there is one
* [x] &#x20;A screenshot of the failing screen — and if the caller can manage it, with the browser developer tools **Network** tab open (F12), showing the failed request

One thing to be aware of before attaching anything: logs and screenshots from this system can contain citizens' names, phone numbers and complaint text. The redaction guidance in the [incident report](/complaints-management/deploy/operations-handbook/incident-report.md) covers what to strip.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.digit.org/complaints-management/deploy/operations-handbook/l1-first-response.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.