Skip to main content
The indexed facts tell Pavo everything at once, but not in a shape a human can read or trust. The tribal book is the distilled version: a chaptered account of how your system actually works: what it is, why it exists, how its metrics are defined, and where it breaks. It is the first artifact you review, and the one you own. The name is deliberate. This is the tribal knowledge that normally lives in a few senior engineers’ heads, written down and kept current.

​
Anatomy of the book

Every book is organized into the same chapters, so once you learn one system’s book you can read any other. Each chapter is written from the facts extracted during indexing, and every claim carries its citation.

​
How metrics are captured

The metrics chapter is the one worth the most of your attention, because a wrong metric definition silently corrupts every investigation that uses it. Pavo documents each metric the way a careful analyst would. For every metric, the book captures:
  • Canonical definition: what the metric means, in one agreed form, so there is no ambiguity about which version is “the” metric.
  • Source tables: the exact tables and columns it is computed from.
  • Computation rules: the ordered steps to compute it: the joins (including the load-bearing ones), the filters, what is included, and what is excluded.
  • Gotchas: the exclusions and edge cases that trip people up (“excludes internal traffic”; “only counts the first event per user per day”).
  • Guardrails: the metrics you must not regress while moving the target metric.
When a system has several plausible definitions of the same metric - three different weighted sums, two activation-rate variants - the book’s job is to record which one is used in production, and to flag the others so no one optimizes the wrong number.
A first-class treatment of guardrails is deliberate. Most tools leave guardrails as an afterthought; here they are part of the canonical metric record, because “did we regress anything” is exactly the question an A/B test has to answer.

​
Everything is grounded

Every line in the book links back to the facts and sources it came from: a piece of code, a query, a table. This means you are never asked to trust the book on faith: you can open any claim and see its evidence. It also means the book stays honest as the system changes, because a claim whose citation no longer holds can be caught.

​
Reviewing and editing

The book is generated by Pavo, but it is owned by you. You have full control over its contents.
1

Read chapter by chapter

Work through the book in order. Ask questions inline, “how does the ranker pick candidates?”, and Pavo answers from the knowledge base.
2

Correct what's wrong

Edit any section directly, or ask Pavo to revise it. When Pavo proposes edits, review them one by one and keep the original, the edit, or a blend.
3

Add what's missing

Upload a plot, a chart, or a document and ask Pavo to situate it in the right chapter. It absorbs the new material and cites it.

​
Verifying the book

Generating the book is human-in-the-loop by design. Where Pavo hits a conflict it cannot resolve - two sources that disagree, an ambiguous definition - it surfaces the question and waits for your answer rather than guessing. Resolving these is the fastest way to raise the book’s accuracy. Mark the load-bearing sections as verified once you have checked them. Verification is what lets agents and teammates rely on a section without re-deriving it.

​
Versions

The book is versioned. As your system evolves - a new ranker ships, a metric is redefined - you can revise the book and keep the history of how your understanding changed. Older versions remain available, so a claim can always be traced to the moment it was true.

​
Next steps

Knowledge bench

Score how correct and complete the book really is.

Knowledge hub

Where new findings extend the book over time.