RULES.md

RULES.md sits at the root of the project folder. Polaris adds it to every chat, so it is the most important context file you write. It tells the agent what the business is, where to find things, and how to query and answer.

Keep it short

Because RULES.md is sent with every message, every line costs time and money on every question. Give it two jobs only:

1. Point the way. Tell the agent which file, table or skill answers which kind of question.
2. Set broad rules. Say how to query and how to answer.

Put details elsewhere and point to them: column descriptions in the table docs under databases/, long definitions in docs/, metrics in the semantic layer, and task recipes in skills. Do not repeat in RULES.md what already lives in another file.

Suggested sections

Section	What to write
Business overview	Two short paragraphs: what the organization does, and what the data is for.
Data architecture	The databases, how data gets there, and the main sources.
Context map	Where everything lives: what each table folder contains, key docs and what they cover, the semantic layer.
Core data models	The most used tables, one line each, with grain, keys and join pitfalls.
Key metrics	How to compute each important metric, unless a semantic layer already defines it.
Date filtering	Two or three example filters, such as “last 30 days” and “current month”.
Analysis process	The steps to follow: read the context, check real column values before filtering, query, check the result.
Answer style	How to present answers: units, rounding, when to draw a chart.

Example

This is a shortened excerpt in the style of the example project:

## Core data models

- `tcga_patients`: one row per patient (`patient_id`). Clinical fields and survival.
- `tcga_samples`: one primary tumour per patient, plus an optional normal (`tissue_role`).
  Always filter `tissue_role = 'tumor'` unless the question is about normal tissue.
- `tcga_somatic_mutations`: one row per mutation. Filter `is_nonsynonymous` for
  protein-altering mutations.

## Key metrics

- Mutation frequency = patients with at least one protein-altering mutation in the gene
  divided by all patients in the cohort, not only patients with any mutation.

## Answer style

- Give percentages with one decimal.
- Say which cohort (KIRC, BLCA or both) the numbers cover.

Rules for some groups only

You can show a block only to members of certain user groups:

{% if group("oncology") %}
When asked about trial eligibility, read docs/eligibility.md first.
{% endif %}

• Group names are not case-sensitive.
• group("a", "b") matches members of either group.
• Blocks can be nested.
• Polaris removes blocks for groups the user is not in.

See Users and roles for how to set up groups.

Check your rules

Measure every change to RULES.md with tests. A rule that sounds right can still make answers worse. See Context engineering for a working method.