Skip to main content

How to create an analytics playbook

An analytics playbook is a short document of data-backed blocks, such as KPI tiles, tables, and charts, that ends with a conclusion. This guide shows how to ask Forge or Guide to build one from your semantic layer.

info

You may use the coginiti-retail-tutorial project as a ready-made example.
Available here: https://github.com/coginiti-dev/coginiti-retail-tutorial
For a complete walkthrough see: Coginiti Retail Project Complete Workflow Tutorial

Prerequisites​

To understand what a playbook is and why it works this way, see Analytics playbooks overview.

Solution​

1. Start a new chat​

Open the AI panel (the panel is titled with your assistant's name, Coginiti Forge or Coginiti Guide) and start a new conversation:

  • Forge - click + New Chat. playbook_ai_chat_new.png

  • Guide (Consumer role) - the panel has no + New Chat button. Click + in the tab bar. playbook_ai_chart_new_guide.png

2. Turn on Playbook mode​

In the message box, switch on Playbook mode (bottom left, on the same row as the Send button). playbook_ai_chat_mode.png

The switch is off by default and is locked while the assistant is responding. The setting belongs to the chat, so you can turn it on or off before each message.

When the switch is on, the message box shows Describe the analysis you want as a playbook.... In an empty chat, the usual welcome is replaced with Ask for an analytics playbook and four starter prompts:

  • Review key metrics
  • Explore a trend
  • Compare performance
  • Build a report

playbook_ai_chat_prompts.png

Selecting a starter prompt puts a ready-made request into the message box. It is not sent until you edit it, if you want to, and click Send.
Each starter prompt asks the assistant to help you choose the semantic layer, the metrics, and the reporting period first.

playbook_ai_chat_example_from_prompt.gif

note

Playbook mode gives the assistant permission to build a playbook.
It does not force one. A greeting, a follow-up question, a single number, a single chart, or an unclear request is answered as a normal chat message.

The reverse also works. If you ask for a playbook by name, for example "Build a playbook...", the assistant can build one with the switch off.
The switch then turns on by itself, so your next message is read the same way.

3. Describe the analysis​

Write the request in plain language. Include what you can:

  • the measures to report, such as revenue or order count
  • the breakdowns, such as by region or product category
  • the period, such as last quarter or calendar year 2025
  • what to compare against, such as the previous period
Build a playbook reviewing Q3 2026 sales: net revenue and order count against Q2,
revenue by region, and the top 10 products by revenue.

playbook_ai_chat_example_general.png

If the request names a period, every block in the playbook uses that period.

If something cannot be worked out from your semantic layer or the conversation, the assistant asks first. Answer its questions, pick an option, or choose Skip to let it decide. See Answer the agent's questions.

4. Review the plan (Forge only)​

With Forge, the assistant shows you the whole plan once, before anything runs. The plan appears in a Review Query card in place of the message box. This is the only interruption during a run.

playbook_ai_chat_review_plan.png

  • Read each block's description and its query. Click the expand icon (View full query) to read the plan in a larger panel.
  • Click Confirm to run the plan as shown.
  • Click Revise, type what should change in What should change?, such as a different period, another breakdown, or fewer blocks, and click Revise again. The assistant shows the updated plan for review. Click Back to return without changes.
  • Click Reject to cancel the playbook.

While you review, the playbook card above already lists the planned blocks with a Pending status.

playbook_ai_chat_pending_blocks.png

With Guide, there is no plan to review. The playbook runs as soon as the assistant has what it needs, and queries are never shown. See Forge and Guide explained for the difference between the two.

5. Watch the playbook build​

A playbook card appears in the chat with a Generating status. Above it, a checklist shows the progress of the run. The steps are:

  • Reading governed semantic models
  • Agreeing what to measure - only when the assistant needs to ask you something
  • Checking the query
  • Waiting for your review - Forge only. Guide shows this step too, but it stays unticked
  • Building the blocks
  • Drawing the conclusion

Completed steps are ticked, and steps a run did not need stay unticked. Each block shows Pending until its data arrives.

playbook_ai_chat_generating_status.png

6. Read the finished playbook​

The card header shows the playbook title, the number of blocks (the conclusion counts as a block), the semantic layer the data came from, and the date and time it ran. The status is one of:

StatusMeaning
GeneratingThe playbook is still being built.
ReadyAll blocks were built.
PartialSome blocks failed, and others answered. The playbook is still worth reading.
ErrorNo block could be built, or the run failed or was denied.

playbook_ai_chat_card_header.png

Below the header, blocks are numbered in reading order: headline numbers first, detail after, and the Conclusion last.

  • KPI block - tiles with the current value. When the request includes a comparison, such as the previous year or period, each tile also shows the change against it. The arrow shows whether the value went up or down. The color shows whether that change is good or bad for the metric, for example red for falling sales.
  • Query block - rows shown as a grid, or drawn as a chart. On a chart, click Chart settings to pick a different chart type. Click the expand icon to open the block in the preview panel, where you can switch between Grid and Chart and use Columns and Filters.
  • Conclusion - an AI analysis written from the blocks above it.

playbook_ai_chat_card_blocks.png

Each block has an info icon next to its title. Hover over it to see what the block shows and how it is worked out, including the period it covers.

playbook_ai_chat_block_info.png

After the card, the assistant adds a short message that sums up the playbook and notes anything it does not cover.

playbook_ai_chat_sum_up.png

7. Ask for a different version​

To get a different playbook, send a new request in the same chat, such as "Build the same playbook for Q2 2026." Keep Playbook mode on so the assistant treats it as a request for a document.

playbook_ai_chat_different_playbook.gif

Troubleshooting​

The assistant answered in text instead of building a playbook. Playbook mode only builds a document when the request clearly asks for an analysis or report with several measures or a comparison. Rephrase the request to say what you want covered, or start it with "Build a playbook...".

The status is Partial. Some blocks could not be built. Each failed block shows an Error status and the reason in its place. Ask for a narrower version of the failed part, or a different breakdown.

The status is Error and the assistant says nothing was built. The assistant does not retry a failed playbook on its own. Narrow the question, name the blocks you want, or set an explicit period, then send it again.

The Playbook mode switch is disabled. The switch is locked while the assistant is responding. Wait for the response to finish or stop it.

The assistant cannot build any block. Check that your catalog project has a semantic layer and that you can run semantic queries. Playbooks are built from the semantic layer, not from raw tables.


tip

For more information about other exciting Coginiti features visit our documentation

Thank you for choosing us!​