> For the complete documentation index, see [llms.txt](https://docs.sealights.io/knowledgebase/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sealights.io/knowledgebase/setup-and-configuration/integrations/user-story-coverage/examples.md).

# Deployment patterns

Choose the pattern that matches your rollout goal.

Use the expandables for the shortest path. Use the linked reference pages for field details.

{% hint style="info" %}
Use [Installation and first run](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/installation.md) for the first successful run.
{% endhint %}

{% hint style="warning" %}
Prefer the Jira plugin or ADO plugin paths when possible. Use Jira custom fields only for legacy Jira setups.
{% endhint %}

### End-to-end reporting workflows

<details>

<summary>SeaLights auto-tagging</summary>

Use this when SeaLights already tags code changes during build reporting.

{% stepper %}
{% step %}

### Confirm the data path

Confirm your ticket source in [Data sources](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/configuration/data-sources.md).

Confirm your target in [Publication targets](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/configuration/publication-targets.md).
{% endstep %}

{% step %}

### Generate report data

Run the report-generation flow from [Report Generation](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/cli-reference.md#report-generation).

Use `--ticket-source jira` or `--ticket-source ado` to match your source system.
{% endstep %}

{% step %}

### Publish the result

Publish issue KPIs or detailed pages from [Publish Analytics](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/cli-reference.md#publish-analytics).
{% endstep %}
{% endstepper %}

#### Expected outcome

* No separate tagging step runs.
* Coverage comes from existing SeaLights tagging data.
* The flow stays short for recurring reports.

</details>

<details>

<summary>Manual tagging</summary>

Use this when auto-tagging is unavailable or too limited for your build flow.

{% stepper %}
{% step %}

### Tag source changes

Choose the tagging command in [Source Tagging](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/cli-reference.md#source-tagging).

Use `--days-back` for pull-request tagging.

Use `--since-date` for history-based tagging.
{% endstep %}

{% step %}

### Generate report data

Run the report-generation flow from [Report Generation](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/cli-reference.md#report-generation).
{% endstep %}

{% step %}

### Publish the result

Publish issue KPIs or detailed pages from [Publish Analytics](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/cli-reference.md#publish-analytics).
{% endstep %}
{% endstepper %}

#### Expected outcome

* Source changes are tagged before coverage is calculated.
* Ticket-linked coverage works without auto-tagging.
* Downstream publishing stays unchanged.

{% hint style="warning" %}
Use this path only when auto-tagging does not fit your workflow.
{% endhint %}

</details>

### Issue coverage KPIs

#### Sprint coverage

Use this when you want sprint tickets updated where teams already review work. Choose the platform that matches the KPI destination.

{% tabs %}
{% tab title="Jira" %}
**✅ Prerequisites**

* Your JQL returns the sprint tickets you want.
* Jira publishing is configured.
* Report data generation already works.

**🚀 Steps**

{% stepper %}
{% step %}

#### Configure the ticket query

Set the JQL filter in Data sources.
{% endstep %}

{% step %}

#### Generate report data

Run the Jira report flow from Report Generation with `--ticket-source jira`.
{% endstep %}

{% step %}

#### Publish sprint coverage

Use the Jira publishing path in Publish Analytics.
{% endstep %}
{% endstepper %}

**📤 Expected outcome**

Jira issues show updated sprint coverage values. Teams review coverage without leaving Jira.
{% endtab %}

{% tab title="Azure DevOps" %}
**✅ Prerequisites**

* Your WIQL returns the sprint work items you want.
* Azure DevOps publishing is configured.
* Report data generation already works.

**🚀 Steps**

{% stepper %}
{% step %}

#### Configure the work item query

Set the WIQL in Data sources.
{% endstep %}

{% step %}

#### Generate report data

Run the Azure DevOps report flow from Report Generation with `--ticket-source ado`.
{% endstep %}

{% step %}

#### Publish sprint coverage

Use the Azure DevOps publishing path in Publish Analytics.
{% endstep %}
{% endstepper %}

**📤 Expected outcome**

Azure DevOps work items show updated sprint coverage. Coverage follows the WIQL result set.
{% endtab %}

{% tab title="Legacy Jira" %}
**✅ Prerequisites**

* Jira custom field IDs are defined.
* Jira write access is available.
* Report data generation already works.

**🚀 Steps**

{% stepper %}
{% step %}

#### Configure the query and field IDs

Set the JQL filter in Data sources. Set the field mapping in Publication targets.
{% endstep %}

{% step %}

#### Generate report data

Run the Jira report flow from Report Generation with `--ticket-source jira`.
{% endstep %}

{% step %}

#### Publish sprint coverage

Use the legacy Jira publishing path in Publish Analytics.
{% endstep %}
{% endstepper %}

**📤 Expected outcome**

Jira custom fields are updated with sprint coverage values. Existing legacy dashboards keep working.
{% endtab %}
{% endtabs %}

### Detailed coverage reports

#### Feature coverage

Use this when teams need page-based coverage for a feature, epic, or cross-ticket review. Choose the destination that matches where teams review full coverage pages.

{% tabs %}
{% tab title="Confluence" %}
**✅ Prerequisites**

* Confluence access is configured.
* The target space and parent page are known.
* Report data generation already works.

**🚀 Steps**

{% stepper %}
{% step %}

#### Configure the target

Set the Confluence target in Publication targets.
{% endstep %}

{% step %}

#### Generate report data

Run the report flow from Report Generation.
{% endstep %}

{% step %}

#### Publish detailed pages

Use the Confluence publishing path in Publish Analytics.
{% endstep %}
{% endstepper %}

**📤 Expected outcome**

A summary page is created or updated in Confluence. Ticket-level pages are published under the target parent page. Teams get stable links for feature-level review.
{% endtab %}

{% tab title="Azure DevOps Wiki" %}
{% hint style="info" %}
Azure DevOps Wiki is a planned target. It is not the current production path. Azure DevOps Wiki support is planned by EOY2026.
{% endhint %}

**🚀 Steps**

{% stepper %}
{% step %}

#### Keep the current production target

Continue to publish detailed pages to Confluence for now.
{% endstep %}

{% step %}

#### Track the future destination

Record Azure DevOps Wiki as the planned target in your rollout plan.
{% endstep %}
{% endstepper %}

**📤 Expected outcome**

Detailed publishing still goes to Confluence today. Azure DevOps Wiki remains the planned future destination.
{% endtab %}
{% endtabs %}

#### CI/CD automation

Use this when coverage must run on a schedule or as part of delivery gates. Choose the platform tab that matches your pipeline.

{% tabs %}
{% tab title="GitHub Actions" %}

```yaml
# .github/workflows/coverage-report.yml
name: User Story Coverage Report

on:
  schedule:
    - cron: '0 2 * * *'  # Daily at 2 AM
  workflow_dispatch:

jobs:
  generate-coverage-report:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v3

      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.9'

      - name: Install dependencies
        run: pip install requests

      - name: Tag PRs
        env:
          SEALIGHTS_API_TOKEN: ${{ secrets.SEALIGHTS_TOKEN }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          JIRA_AUTHORIZATION: ${{ secrets.JIRA_AUTH }}
        run: |
          python3 US_SRC_tag_repos_by_github_prs.py \
            --settings settings \
            --days-back 30

      - name: Generate reports
        env:
          SEALIGHTS_API_TOKEN: ${{ secrets.SEALIGHTS_TOKEN }}
          JIRA_AUTHORIZATION: ${{ secrets.JIRA_AUTH }}
        run: |
          python3 US1_RPT_create_report_info_files.py \
            --settings settings \
            --ticket-source jira
          python3 US2_RPT_create_html_reports.py \
            --settings settings

      - name: Upload reports
        uses: actions/upload-artifact@v3
        with:
          name: coverage-reports
          path: reports/*.html

      - name: Update Jira
        env:
          JIRA_AUTHORIZATION: ${{ secrets.JIRA_AUTH }}
        run: |
          python3 US4_RPT_update_jira.py --settings settings
```

{% endtab %}

{% tab title="Jenkins" %}

```groovy
// Jenkinsfile
pipeline {
    agent any

    environment {
        SEALIGHTS_API_TOKEN = credentials('sealights-token')
        JIRA_AUTHORIZATION = credentials('jira-auth')
        GITHUB_TOKEN = credentials('github-pat')
    }

    stages {
        stage('Setup') {
            steps {
                sh 'pip install requests'
            }
        }

        stage('Tag Code Changes') {
            steps {
                sh '''
                    python3 US_SRC_tag_repos_by_github_prs.py \
                        --settings settings \
                        --days-back 30 \
                        --log-level INFO
                '''
            }
        }

        stage('Generate Reports') {
            steps {
                sh '''
                    python3 US1_RPT_create_report_info_files.py \
                        --settings settings \
                        --ticket-source jira
                    python3 US2_RPT_create_html_reports.py \
                        --settings settings
                '''
            }
        }

        stage('Publish') {
            parallel {
                stage('Confluence') {
                    steps {
                        sh 'python3 US3_RPT_create_confluence_reports.py --settings settings'
                    }
                }
                stage('Jira') {
                    steps {
                        sh 'python3 US4_RPT_update_jira.py --settings settings'
                    }
                }
            }
        }
    }

    post {
        always {
            archiveArtifacts artifacts: 'reports/**/*.html', fingerprint: true
        }
    }
}
```

{% endtab %}

{% tab title="GitLab CI" %}

```yaml
# .gitlab-ci.yml
variables:
  PIP_CACHE_DIR: "$CI_PROJECT_DIR/.cache/pip"

cache:
  paths:
    - .cache/pip

stages:
  - tag
  - report
  - publish

tag_code_changes:
  stage: tag
  image: python:3.9
  before_script:
    - pip install requests
  script:
    - |
      python3 US_SRC_tag_repos_by_github_prs.py \
        --settings settings \
        --days-back 30
  only:
    - schedules

generate_reports:
  stage: report
  image: python:3.9
  before_script:
    - pip install requests
  script:
    - |
      python3 US1_RPT_create_report_info_files.py \
        --settings settings \
        --ticket-source jira
      python3 US2_RPT_create_html_reports.py \
        --settings settings
  artifacts:
    paths:
      - reports/
    expire_in: 7 days
  only:
    - schedules

publish_confluence:
  stage: publish
  image: python:3.9
  before_script:
    - pip install requests
  script:
    - python3 US3_RPT_create_confluence_reports.py --settings settings
  only:
    - schedules

publish_jira:
  stage: publish
  image: python:3.9
  before_script:
    - pip install requests
  script:
    - python3 US4_RPT_update_jira.py --settings settings
  only:
    - schedules
```

{% endtab %}

{% tab title="Azure Pipelines" %}

```yaml
# azure-pipelines.yml
trigger: none

schedules:
  - cron: "0 2 * * *"
    displayName: Daily coverage report
    branches:
      include:
        - main
    always: true

pool:
  vmImage: 'ubuntu-latest'

variables:
  - group: sealights-coverage-secrets

stages:
  - stage: Tag
    jobs:
      - job: TagCodeChanges
        steps:
          - task: UsePythonVersion@0
            inputs:
              versionSpec: '3.9'
          - script: pip install requests
            displayName: 'Install dependencies'
          - script: |
              python3 US_SRC_tag_repos_by_github_prs.py \
                --settings settings \
                --days-back 30
            displayName: 'Tag PRs'
            env:
              SEALIGHTS_API_TOKEN: $(SEALIGHTS_API_TOKEN)
              GITHUB_TOKEN: $(GITHUB_TOKEN)
              JIRA_AUTHORIZATION: $(JIRA_AUTHORIZATION)

  - stage: Report
    dependsOn: Tag
    jobs:
      - job: GenerateReports
        steps:
          - task: UsePythonVersion@0
            inputs:
              versionSpec: '3.9'
          - script: pip install requests
            displayName: 'Install dependencies'
          - script: |
              python3 US1_RPT_create_report_info_files.py \
                --settings settings \
                --ticket-source jira
              python3 US2_RPT_create_html_reports.py \
                --settings settings
            displayName: 'Generate reports'
            env:
              SEALIGHTS_API_TOKEN: $(SEALIGHTS_API_TOKEN)
              JIRA_AUTHORIZATION: $(JIRA_AUTHORIZATION)
          - publish: reports
            artifact: coverage-reports

  - stage: Publish
    dependsOn: Report
    jobs:
      - job: PublishJira
        steps:
          - task: UsePythonVersion@0
            inputs:
              versionSpec: '3.9'
          - script: pip install requests
            displayName: 'Install dependencies'
          - script: python3 US4_RPT_update_jira.py --settings settings
            displayName: 'Update Jira'
            env:
              JIRA_AUTHORIZATION: $(JIRA_AUTHORIZATION)
```

Store `SEALIGHTS_API_TOKEN`, `GITHUB_TOKEN`, and `JIRA_AUTHORIZATION` in an Azure DevOps variable group named `sealights-coverage-secrets`, marked as secret.
{% endtab %}
{% endtabs %}

#### CI/CD reference material

<details>

<summary>Sample ReportInfo JSON structure</summary>

```json
{
  "key": "PROJ-123",
  "title": "Implement user authentication",
  "overallResults": {
    "overall_coverage": 78.5,
    "overall_count": 120,
    "unit_tests_coverage": 85.0,
    "unit_tests_count": 80,
    "integration_tests_coverage": 65.0,
    "integration_tests_count": 40
  },
  "methods": [
    {
      "signature": "com.example.auth.AuthService.login",
      "coverage": 100,
      "testStages": ["Unit_Tests", "Integration_Tests"]
    }
  ]
}
```

</details>

<details>

<summary>Run multiple repositories in parallel</summary>

```bash
#!/bin/bash
# parallel_tagging.sh
cat > repo_list.txt <<EOF
frontend-app
backend-api
mobile-app
admin-portal
EOF

cat repo_list.txt | parallel -j 4 '
  echo "Processing {}"
  python3 US_SRC_tag_repos_by_github_prs.py \
    --settings settings_{} \
    --days-back 30
'
```

</details>

<details>

<summary>Fail the build on low coverage</summary>

```bash
#!/bin/bash
# coverage_gate.sh
THRESHOLD=70
FAILED=false

python3 US1_RPT_create_report_info_files.py --settings settings --ticket-source jira
python3 US2_RPT_create_html_reports.py --settings settings

for report in reports/ReportInfo_*.json; do
  ticket=$(basename "$report" | sed 's/ReportInfo_//;s/.json//')
  coverage=$(jq -r '.overallResults.overall_coverage // 0' "$report")
  if (( $(echo "$coverage < $THRESHOLD" | bc -l) )); then
    echo "FAIL: $ticket at ${coverage}% (below ${THRESHOLD}%)"
    FAILED=true
  fi
done

if [ "$FAILED" = true ]; then
  echo "Coverage gate failed."
  exit 1
fi
```

</details>

<details>

<summary>Send a low-coverage notification</summary>

```bash
#!/bin/bash
# notify_low_coverage.sh
THRESHOLD=60
SLACK_WEBHOOK="$SLACK_WEBHOOK_URL"

python3 US1_RPT_create_report_info_files.py --settings settings --ticket-source jira

for report in reports/ReportInfo_*.json; do
  ticket=$(basename "$report" | sed 's/ReportInfo_//;s/.json//')
  coverage=$(jq -r '.overallResults.overall_coverage // 0' "$report")
  title=$(jq -r '.title' "$report")
  if (( $(echo "$coverage < $THRESHOLD" | bc -l) )); then
    message="Low coverage alert: $ticket - $title has ${coverage}% coverage (threshold: ${THRESHOLD}%)"
    curl -X POST "$SLACK_WEBHOOK" -H 'Content-Type: application/json' -d "{\"text\": \"$message\"}"
  fi
done
```

</details>

### Analytics scope patterns

<details>

<summary>One app and one repo</summary>

Use this when one repository maps to one SeaLights app and one main branch.

```json
{
  "coverage_app_list": [
    {
      "app_regex": "my-app",
      "branch_regex": "main"
    }
  ],
  "repo_list": [
    {
      "repoName": "frontend-app",
      "SealightsAppName": "my-app",
      "SealightsBranchName": "main"
    }
  ]
}
```

#### Expected outcome

Coverage is pulled from one app and mapped back to one repo cleanly.

</details>

<details>

<summary>Several repos in one reporting flow</summary>

Use this when one report must include several repositories.

```json
{
  "repo_list": [
    {
      "repoName": "component-a",
      "SealightsAppName": "component-a",
      "SealightsBranchName": "main"
    },
    {
      "repoName": "component-b",
      "SealightsAppName": "component-b",
      "SealightsBranchName": "main"
    }
  ]
}
```

#### Expected outcome

The same run can cover more than one repository.

</details>

<details>

<summary>Raw stages and grouped stages together</summary>

Use this when you want both detailed stage coverage and a rolled-up KPI.

```json
{
  "test_stages": [
    {
      "name": "Unit_Tests",
      "reportJsonKey": "unit_tests",
      "reportTitle": "Unit Tests"
    },
    {
      "name": "Integration_Tests",
      "reportJsonKey": "integration_tests",
      "reportTitle": "Integration Tests"
    }
  ],
  "grouped_test_stages": [
    {
      "name": "Overall",
      "reportJsonKey": "overall",
      "reportTitle": "Overall Coverage",
      "stages": ["Unit_Tests", "Integration_Tests"]
    }
  ]
}
```

#### Expected outcome

Reports show both stage detail and grouped coverage.

</details>

<details>

<summary>Integration build scope</summary>

Use this when one reported build combines several components.

```json
{
  "coverage_app_list": [
    {
      "app_regex": "my-integration-build",
      "branch_regex": "main",
      "integration_build": true
    }
  ],
  "repo_list": [
    {
      "repoName": "component-a",
      "SealightsAppName": "component-a",
      "SealightsBranchName": "main"
    },
    {
      "repoName": "component-b",
      "SealightsAppName": "component-b",
      "SealightsBranchName": "main"
    }
  ]
}
```

#### Expected outcome

User Story Coverage validates that all required components are in scope.

</details>

### Multi-system examples

<details>

<summary>Jira source to Jira plugin output</summary>

Use this when Jira is both the ticket source and the KPI destination.

{% stepper %}
{% step %}

### Select the tickets

Use the Jira query path in [Data sources](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/configuration/data-sources.md).
{% endstep %}

{% step %}

### Generate the report data

Run the Jira report flow from [Report Generation](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/cli-reference.md#report-generation).
{% endstep %}

{% step %}

### Publish the KPI

Use the Jira plugin path in [Publish Analytics](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/cli-reference.md#publish-analytics).
{% endstep %}
{% endstepper %}

#### Expected outcome

* Jira issues are selected by JQL.
* Coverage is calculated from SeaLights data.
* Jira issues are updated with coverage KPIs.

</details>

<details>

<summary>Azure DevOps source to Confluence output</summary>

Use this when work items live in Azure DevOps and teams review full pages in Confluence.

{% stepper %}
{% step %}

### Select the work items

Use the WIQL path in [Data sources](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/configuration/data-sources.md).
{% endstep %}

{% step %}

### Generate the report data

Run the Azure DevOps report flow from [Report Generation](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/cli-reference.md#report-generation).
{% endstep %}

{% step %}

### Publish detailed pages

Use the Confluence path in [Publish Analytics](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/cli-reference.md#publish-analytics).
{% endstep %}
{% endstepper %}

#### Expected outcome

* Work items are selected by WIQL.
* Coverage is matched to those work items.
* Detailed pages are published to Confluence.

</details>

<details>

<summary>SeaLights and Git tagging to issue coverage KPIs</summary>

Use this when ticket mapping comes from tagging before report generation.

{% stepper %}
{% step %}

### Tag the linked changes

Choose the tagging command in [Source Tagging](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/cli-reference.md#source-tagging).
{% endstep %}

{% step %}

### Generate the report data

Run the report flow from [Report Generation](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/cli-reference.md#report-generation).
{% endstep %}

{% step %}

### Publish the KPI

Use the target-specific path in [Publish Analytics](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/cli-reference.md#publish-analytics).
{% endstep %}
{% endstepper %}

#### Expected outcome

* Recent code changes are tagged with ticket IDs.
* Coverage is linked to those tickets.
* Teams see issue-level coverage in the target system.

</details>

### Tagging workflows

<details>

<summary>Pull request coverage</summary>

Use this when pull requests are the main source of ticket-linked changes.

{% stepper %}
{% step %}

### Choose the tagging source

Use GitHub pull requests when merged PRs are your source of truth.

Use Jira-linked pull requests when tagging must stay limited to Jira query results.
{% endstep %}

{% step %}

### Run the tagging path

Use `US_SRC_tag_repos_by_github_prs.py` or `US_SRC_tag_repos_by_jira_github_prs.py` from [Source Tagging](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/cli-reference.md#source-tagging).

Use `--days-back` to set the PR lookback window.
{% endstep %}

{% step %}

### Continue to reporting

Generate report data in [Report Generation](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/cli-reference.md#report-generation).
{% endstep %}
{% endstepper %}

#### Expected outcome

Recent merged pull requests are scanned and matching ticket IDs are tagged in SeaLights.

</details>

<details>

<summary>Git history tagging</summary>

Use this when pull requests are not your source of truth.

{% stepper %}
{% step %}

### Set the time range

Choose a stable cutoff date for the tagging window.
{% endstep %}

{% step %}

### Run the history path

Use `US_SRC_tag_repos_by_history.py` from [Source Tagging](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/cli-reference.md#source-tagging).

Use `--since-date` to set the history cutoff.
{% endstep %}

{% step %}

### Continue to reporting

Generate report data in [Report Generation](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/cli-reference.md#report-generation).
{% endstep %}
{% endstepper %}

#### Expected outcome

Commits are scanned directly and matching ticket IDs are tagged from commit history.

</details>

<details>

<summary>Jira-linked pull requests</summary>

Use this when tagging must stay limited to tickets returned by the Jira query.

{% stepper %}
{% step %}

### Configure the Jira query

Set the JQL filter in [Data sources](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/configuration/data-sources.md).
{% endstep %}

{% step %}

### Run the constrained tagging path

Use `US_SRC_tag_repos_by_jira_github_prs.py` from [Source Tagging](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/cli-reference.md#source-tagging).
{% endstep %}

{% step %}

### Continue to reporting

Generate report data in [Report Generation](/knowledgebase/setup-and-configuration/integrations/user-story-coverage/cli-reference.md#report-generation).
{% endstep %}
{% endstepper %}

#### Expected outcome

Only pull requests linked to the selected Jira tickets are processed.

</details>


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.sealights.io/knowledgebase/setup-and-configuration/integrations/user-story-coverage/examples.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.