Context engineering

Context engineering is the work of giving Polaris the right information, in the right place, so it answers correctly every time. This page gives a method to follow and the principles behind it.

Playbook

Follow these steps in order. Each one builds on a working result from the one before.

1. Scope the project. Pick the questions the project must answer, and the 10 to 20 tables that answer them. Leave everything else out. More tables means more ways to be wrong.
2. Connect and sync. Configure the databases with columns, preview and profiling, and run pda sync. Check pda debug first.
3. Write RULES.md. Follow the suggested sections. Point to the table docs instead of repeating them.
4. Write tests. One test per key metric, plus date ranges and ambiguous wording. See Tests.
5. Run the tests and read every failure. Sort each failure into one of the categories below, and make the smallest change that fixes it.
6. Repeat until the pass rate is stable. Run with -k 3 and watch pass^k, not only pass@k.
7. Add structure only when tests demand it. Move long sections into docs/ files or skills. Add a semantic layer when metric tests keep failing.
8. Deploy and listen. Deploy the project, then read bad ratings in Chats replay. Turn each real failure into a new test.

Sort failures

Category	Looks like	Fix
Data model	Wrong table or column	Describe the column, or the table’s grain, in its annotations.md.
Dates	Wrong period, or wrong date column	Add an example filter to the date section of RULES.md.
Metric definition	Wrong formula or denominator	Tighten the metric in RULES.md, or add it to the semantic layer.
Interpretation	A reasonable answer to a different reading of the question	Add the team’s meaning of the term to RULES.md.
Test issue	The reference SQL is wrong	Fix the test, not the context.

Principles

• Less is more. Every line of context competes for the agent’s attention. Remove what does not change answers.
• One source of truth. Define each metric and each rule in exactly one place. Two definitions of the same thing make the agent pick one at random.
• Point, do not copy. RULES.md is an index. It sends the agent to the right file instead of repeating that file.
• Use real values. Ask the agent to check profiling.md before it filters on a value, so it filters on values that exist.
• Be explicit about grain and joins. Say what one row means in each core table, and which joins duplicate rows.
• Measure every change. A rule that sounds right can make answers worse. Run the tests before and after.
• Fix the context, not the answer. When an answer is wrong, find the missing or wrong context. Do not add a rule for one question.
• Hide the answers. Keep tests out of the agent’s view with .pdaignore.

Tools that help

The skills for coding agents automate much of this playbook. setup-context, write-context-rules, create-context-tests and audit-context follow these steps with you in Claude Code or Codex.