Tracking Agent docs

How to review a Tracking Agent proposal

Review a tracking proposal on the Datalyze review page or with comments on the pull request: approve, edit or reject each item, then sign off. Reviewers sign in with GitHub only and need no Datalyze account. Whichever way you review, each decision is a /datalyze comment posted from your own GitHub account.

The people in reviewers in .datalyze/config.yaml, as GitHub logins or teams written @org/team. The runner reads that file from the pull request's base branch, or from the default branch when the base has none, never from the pull request itself, so a change to reviewers counts only once it merges. It checks the GitHub account that posted each comment, never a commit's author field.

For team entries, your GitHub App needs read access to your organisation's members, which setup asks for when the repo belongs to an organisation. Set allow_author_approval: false to stop a pull request's author deciding on their own tracking: approving, rejecting, dropping, answering, signing off or skipping. Rejecting every item also turns the check green, so it counts as a decision too.

The review inbox lists open pull requests labelled datalyze in your own repos and in every organisation you belong to. The runner adds that label the first time a pull request needs a person, and its summary comment links straight to that pull request's review page. You can also paste a pull request link.

Signing in asks GitHub for the repo and read:org scopes, so the page can read and write the proposal file and see your organisations. The token passes once through Datalyze's exchange step on its way back to your browser, and isn't stored there. After that it stays in your browser tab and goes only to api.github.com. The review, setup and sign-in pages load no analytics and no third-party scripts.

• What changes and why, in one sentence.
• The question the change answers.
• The evidence: the code it's based on, and for existing items the data and the query behind it.
• Whether it's breaking, and how confident the agent is.
• The fields you can edit, and a note box for instructions the agent must follow.

Items are grouped into adding, changing and deprecating, with breaking items first, and events and user properties shown separately. The plan before and after is a table, not YAML, and a list shows the existing events the agent checked and found unaffected, so you can see the impact check happened.

1. Open the pull request's review page from the inbox or from the link in the agent's comment.
2. Edit any field that's wrong. Your edits go into the item's final copy; the agent's proposed copy stays for comparison.
3. Add a note if the agent should do something specific. It's binding. Mark it as a rule to add it to .datalyze/conventions.md for every future pull request.
4. Add an event or property the agent missed.
5. Approve or reject each item. A rejection needs a reason, which goes into .datalyze/decisions.yaml.
6. Submit. The page commits the edited proposal file to the pull request's branch with your GitHub token, then posts one comment from your account with the commands, such as /datalyze approve p1,p3 @1a2b3c4 and /datalyze reject p2 "reason". The @1a2b3c4 names the version of the proposal file you reviewed.

GitHub runs the workflow on that comment exactly as if you had typed it, and the runner checks you're a reviewer the same way.

Only additive, high-confidence items. Breaking changes, deprecations, money events and anything below high confidence each need approving by name. Money events are those whose names match money_patterns in .datalyze/config.yaml; the default list includes payment, order, purchase, checkout and subscription. A plain /datalyze approve skips the rest and says which items are left.

The approval is tied to the item's content when you gave it. If anyone edits the item afterwards, it goes back to awaiting review and needs approving again. An approval sent from the review page also names the version of the proposal file you saw, so if the file changed between your review and your submit, the runner refuses the approval and says the proposal changed since you reviewed it.

Once the agent has pushed its verified commit, the review page shows each item with its verification results, what each event actually sent next to what the plan expects, any wording the agent refined after approval, and a link to the code diff. Signing off posts /datalyze signoff and turns datalyze/tracking green on that commit. On GitHub, comment the same command.

Commands run only from the workflow on your default branch, because GitHub runs issue_comment workflows from there. Put each command on its own line. Editing an old comment never adds a command, and comments from bots never start a run.