Appendix A: Tool Atlas

Status: drafted · Time: 10 min · Audience: everyone Outcome: Choose the right AI tool surface for the job instead of treating every tool as interchangeable.

What this is. A working map of the AI surfaces named across the playbook. Use it when you are unsure whether a job belongs in Claude Code, Claude.ai, Claude Design, Cowork, Compass, PM tracer, Analytics Agent, Slash, Cursor, Codex, or a more traditional IDE.

The short version

Tool	Reach for it when	Avoid using it for
Claude Code	You are changing files in a repo, running commands, reading errors, or iterating on a PR.	Sensitive data dumping, long-form stakeholder writing, or work where the repo is irrelevant.
Claude.ai	You need a thinking partner for synthesis, drafts, analysis, or exploration outside a codebase.	Repo edits, terminal work, or anything that must inspect local files.
Claude Design	You are exploring UI, deck, or design concepts with Razorpay design-system context.	Repo edits, Blade compliance gates, or anything that must ship through a PR.
Cowork	You want a guided enterprise assistant with approved connectors and repeatable non-code workflows.	Deep codebase surgery or local build/test loops.
Compass	You need Razorpay-specific skills, hooks, MCPs, and policy-aware workflows inside Claude Code.	One-off general chat. Compass is the overlay, not the conversation surface.
hash (`rzh`)	You need to install or sync certified skills, diagnose local harness health, or inspect MCP and session status on your laptop.	Running agents, managing credentials, or replacing Claude Code or Compass. hash manages local harness state; it is not the assistant.
PM tracer	You want your PM/Product Claude Code usage to count toward the AI Adoption Leaderboard after your setup is GREEN.	Debugging, answering questions, or trying to “game” adoption through token spend. It is instrumentation, not an assistant.
Analytics Agent	You need the standalone Self Serve Analytics path for metric questions, lineage checks, or health reviews.	Native-Windows hand ports, ad-hoc database access, or metric work before the plugin is onboarded.
Slash	You need remote internal research or a bounded repo task: use knowledge-first mode to understand, or execution mode to change code and raise a PR.	Local uncommitted work, an interactive dev loop, or a task whose repo and success criteria are still unclear.
Cursor	You want an IDE-native coding assistant inside an editor workflow.	Program-specific belt flows that depend on Compass conventions.
Codex	Current support guidance confirms that you have access for a bounded implementation, verification, or second-agent check.	General quota fallback, or certification work that depends on Compass skills, Razorpay connectors, or Claude Code guardrails.

The pattern: pick the surface that can see the right context and take the right action. A better model with the wrong visibility still fails.

How to read each tool

For every surface in this atlas, you should be able to answer five questions before you start work in it. Once you can, you have learned the tool well enough.

What can it see? Files, repo state, browser tabs, internal connectors, the terminal, nothing at all? Visibility is the first constraint.
What can it do? Edit, run, fetch, send, post, deploy, request review, file a ticket? An assistant that can only suggest is different from one that can act.
Where does it persist? Are conversations saved? Is there a project, workspace, or skill registry that accumulates? Is the work disposable?
Who else can read what happens? Personal session, team workspace, audited org workspace, public chat — the answer should be obvious before you paste anything sensitive.
What is the cost of being wrong? A typo in Claude.ai is harmless. A typo in a Claude Code session pointed at a production repo is not. The wrong surface multiplies small mistakes.

Tool cards

Claude Code

Surface type. A terminal application that runs against a local working directory. The agent reads files, proposes edits, executes commands, and asks for approval on anything it cannot do safely on its own.

Default context. The directory you started it from, the open repo, the Compass plugin payload (skills, hooks, MCPs, slash commands), and any files you point it at during the session.

What it can see. Local files inside the working directory, output of commands you let it run, connectors exposed by Compass MCPs, and your prompt history within the session.

What it can do. Edit files, run tests, run package managers, run scripts, open and amend pull requests via gh, invoke skills, call connectors. With permission, almost anything a developer would do at the command line.

What it cannot do well. Long-form synthesis from data it cannot see, browser-style research without a connector, and tasks where the repo is irrelevant. It is not a chat companion; it is a builder.

Common failure modes. Pointed at the wrong directory. Auth not refreshed. Compass plugin out of date. Asked to do work that has no repo footprint. Treated as a search engine.

Belt relevance. Default tool from White Belt onward.

Claude.ai

Surface type. Browser chat at claude.ai. Same family of models as Claude Code, no file access, no repo context, no Compass.

Default context. What you paste into the conversation, plus any files you upload, plus the conversation history.

What it can see. What you give it. Nothing more.

What it can do. Reasoning, drafting, summarisation, exploration, stakeholder writing, and breaking a tangled idea into a sequence. Excellent for product, ops, design, and writing work.

What it cannot do. Touch a file you have not uploaded. Run a command. Read your repo. Apply Razorpay-specific conventions on its own.

Common failure modes. Drafting code there and pasting it into a Razorpay repo without going back through Claude Code. Code from Claude.ai does not know about Blade conventions, repo guardrails, or pre-ship checks. The fix is a habit: think in Claude.ai, ship in Claude Code.

Belt relevance. All belts use Claude.ai for thinking and writing; none use it for shipping.

Claude Design

Surface type. A Claude design workspace at claude.ai/design, separate from Claude Code. It is useful for visual ideation and design-system-aware drafts, not for changing source code.

Default context. The design system project you select in the workspace. For Razorpay design work, the Blade Design System project provides tokens, component anatomy, states, interaction patterns, and approved deck templates where available.

What it can see. The design assets, deck inputs, screenshots, and prompt context you provide inside that workspace. It does not automatically see your local repo, your branch, or the Compass plugin context loaded in Claude Code.

What it can do. Generate and iterate on design concepts, UI explorations, and Razorpay-branded deck drafts using the selected design system. A good prompt is explicit: “Use the Blade design system” or “Use the approved deck template.”

What it cannot do. Open a PR, run tests, verify Blade compliance in a codebase, or replace the Blade MCP / Blade audit path inside Claude Code. If the work needs to ship, move the intent into Claude Code and let the repo plus Compass guardrails drive the implementation.

Common failure modes. Treating a pretty Claude Design output as production-ready code. Mixing up Claude Design with Claude Code. Forgetting that generated decks and visuals still need human review for names, numbers, confidential data, and brand fit.

Belt relevance. Useful for designers and PMs from Yellow Belt onward as an ideation surface. Green Belt design-to-code work still ships through Claude Code with Figma, Blade, Code Connect, and review evidence.

Cowork

Surface type. A desktop application aimed at builders who are not living in a terminal. Folder-first UI, the same agent loop, the same skills system, designed for workflow-heavy non-code tasks.

Default context. A selected folder on your machine and the documents within it, plus connectors that the host application has approved.

What it can see. Files in the selected folder, attached documents, and the connector layer the application exposes.

What it can do. Build documents, run multi-step research, automate repeatable office workflows, and call into the same skill system that powers Claude Code’s polished outputs.

What it cannot do. Replace Claude Code for repo work. Cowork is not optimised for editing live source trees; the moment work becomes “open this PR in our repo,” move into Claude Code.

Common failure modes. Trying to ship a feature from Cowork. Using it as a free-form chat surface when Claude.ai would be faster.

Belt relevance. White and Yellow belts use it heavily for non-code workflows; Green and Black belts treat it as a sibling surface to Claude Code.

Compass

Surface type. A plugin layer that runs inside Claude Code. Not a separate window. When installed, it injects skills, hooks, MCPs, and slash commands that make Claude Code aware of Razorpay’s conventions.

Default context. Whatever Claude Code already has, plus the org’s curated skill bundle, plus the connector list approved for the program.

What it can see. Whatever Claude Code can see. Compass does not see beyond its host.

What it can do. Trigger named workflows (/setup-verify, /pre-ship-check, design and review skills), enforce hooks, and route specialised tasks to subagents.

What it cannot do. Run by itself. If Claude Code is broken or unauthed, Compass is not running.

Common failure modes. Installed but stale — skills loaded from an older version that does not match current conventions. Always confirm version through the verification skill before high-stakes work.

Belt relevance. Required from White Belt setup. Becomes the centre of gravity at Green and Black, where builders begin authoring their own skills.

hash (`rzh`)

Surface type. Razorpay’s local harness manager for a development laptop. It manages files and health checks around Claude Code; it does not run an agent or replace the Compass plugin.

Default context. Its local checkout, the harness files it installed, the certified skill catalog, and the Claude Code and project MCP configuration it can inspect. It keeps its own runtime under ~/.hash/.

What it can do. Link certified skills into Claude Code, diagnose the installation with copyable fixes, probe MCP health, show local session status, open a localhost-only dashboard, and update or uninstall what hash configured.

What it cannot do. Run a prompt, act on a remote repo, or manage credentials. Claude Code remains the agent surface; Compass remains the program plugin; hash keeps the local harness around them inspectable.

Try the setup-to-health loop. Use this when current enablement asks you to install hash:

git clone git@github.com:razorpay/hash.git ~/src/hash
cd ~/src/hash
./setup
rzh --version
rzh doctor

Do not continue on a red diagnostic. Apply the fix printed beside the failed check, then rerun rzh doctor. Once the check is clean, use rzh status for the one-screen view, rzh mcp --probe for a fresh MCP probe, or rzh ui for the local dashboard. The official guides carry the detailed contracts.

Common failure modes. Typing hash instead of rzh calls a shell builtin. If rzh is not on PATH, follow the command path printed by setup or the troubleshooting guide. A 401 or 403 MCP probe means unauthenticated, not down; authenticate through the approved route rather than editing credentials into config. If existing skill directories block linking, preview rzh sync --adopt --check before adopting only byte-identical copies.

Belt relevance. Useful from White Belt onward when a cohort or tooling owner requires it. Green and Black builders also use its skill, MCP, and review-depth views; W.5 remains the canonical Day-1 setup contract.

PM tracer (`rzp-pm-tracing`)

Surface type. A Claude marketplace plugin that instruments PM/Product Claude Code usage for the AI Adoption Leaderboard. It is an add-on after the core Claude Code setup is GREEN, not a Quest W-0 prerequisite.

Default context. The Claude Code sessions, skills, and tool-usage signals that the tracing plugin emits once installed and healthy.

What it can see. Usage signals from your PM/Product AI workflows. The leaderboard rewards applied usage patterns and shipped work, not raw token burn or cost spend.

What it can do. Feed the PM adoption dashboard so your AI workflow activity is visible, check the tracing pipeline through /tracing-doctor, and make adoption gaps easier to debug.

What it cannot do. Answer metric questions, edit repos, improve the substance of your work, or turn token-heavy sessions into meaningful adoption. It measures; it does not build.

Common failure modes. Installing it before Claude Code is healthy. Forgetting to restart Claude Code before running /tracing-doctor. Treating the leaderboard as a token-spend contest instead of an applied-work signal.

Belt relevance. PM/Product add-on immediately after White Belt setup. H.7 carries the exact install sequence; this atlas explains what surface you are installing.

Analytics Agent

Surface type. A standalone Claude marketplace plugin for Self Serve Analytics work. It replaces the old Compass querying-metrics path for metric questions.

Default context. The approved SSA connector setup, onboarding state, and analytics sources exposed through the plugin once /analytics-setup and /analytics-onboard are complete.

What it can see. The metric, lineage, and health-review surfaces exposed by the SSA plugin. It should not be treated as a license to paste raw credentials, export customer data, or bypass data-access approvals.

What it can do. Run metric questions through /analytics-query, support /analytics-review health checks, and keep PM analytics work on the maintained SSA path instead of scattered one-off SQL snippets.

What it cannot do. Fix missing data-access grants by itself, replace source-of-truth dashboards, or run reliably on native Windows today. The current plugin assumes a Unix-like surface for shell wrappers, python3, hooks, and POSIX locking.

Common failure modes. Using the deprecated querying-metrics habit when the standalone plugin is the current path. Running a stale plugin whose bundled metric catalog no longer matches the current definitions. Installing on native Windows and trying to hand-port the plumbing. Asking broad business questions before the metric/source is named. Treating one returned row as proof that the query honoured its inputs—or that its units and arithmetic are correct.

Belt relevance. PM/Product add-on after White Belt setup; useful from Yellow Belt onward for metric-backed product work.

Refresh after a catalog change

Analytics Agent carries its metric catalog inside the installed plugin. A metric owner can switch a domain or correct a definition in the source catalog while your local copy keeps running without an obvious error.

After an announced metric cutover or catalog correction, refresh before the next /analytics-query or /analytics-review:

In Claude Code, choose /plugin → Marketplaces → razorpay-marketplace → Enable auto-update. If you keep updates manual, run:
Terminal window
```
claude plugin marketplace update razorpay-marketplace
claude plugin update analytics-agent@razorpay-marketplace
```
Restart Claude Code so the refreshed commands and catalog load.
Rerun the metric question and inspect the receipt. Confirm that its source table matches the announced path before using the number.

Stop if the plugin did not refresh, the commands do not load after restart, or the receipt still names the superseded source. Capture the announcement, metric, expected source, observed source, and redacted error; route that evidence to the Analytics Agent owner instead of guessing a table name.

Current Trino route: distinguish setup from data access

Analytics Agent still uses the Trino MCP for Trino-backed metrics. Data Platform has retired the shared service-account route in favour of Trino MCP 2.0’s per-user, region-specific Datum authentication. However, the current released plugin still declares a credential-free MCP and its /analytics-setup flow does not configure those per-user headers. The repo-owned Trino CLI migration remains under review in claude-plugins #1075; it is not a released fallback yet.

Use this decision card before diagnosing the metric:

Refresh Analytics Agent and restart Claude Code
  → rerun /analytics-setup and its Trino probe
  → probe passes? Ask the metric question and inspect its receipt
  → 401 "User not authenticated"? Stop: the auth route is not ready
  → 403 or profile denial? Stop: access approval is missing

A 401 on SELECT 1 is an authentication-path failure, not evidence that the metric, table, or VPN is broken. Capture the refresh status, exact probe, region or gateway, timestamp, and redacted error in the active Analytics Agent thread, then follow the owner-confirmed setup route. Do not paste a Datum token into chat, commit it, or hand-edit the installed plugin’s .mcp.json; plugin updates can overwrite that file, and an added MCP may not be the route the Analytics Agent skill invokes.

Until the plugin owns per-user setup or the CLI migration ships, treat Trino-backed Analytics Agent answers as blocked when this probe is red. Use the source-of-truth dashboard or another owner-approved source for the decision rather than silently changing transport. Per-user authentication changes identity and auditability, not the underlying data-access policy, timeout, row cap, or read-only boundary.

Prove the inputs before trusting the number

A query can run, return a plausible number, and still ignore the parameter that made the question specific. Execution proves that the plumbing works; it does not prove that a date, segment, or comparison window changed the computation.

Run this check before a parameterised metric answer drives a product decision, and whenever a certified query is added or modified. Week-on-week and month-on-month metrics need it most: both comparison windows must be distinct and tied to the requested period.

Write the expected behaviour first. Choose a date, filter, or segment whose effect you can explain. Use an owner-approved dashboard, a small manual count, or a deliberately empty window as the anchor.
Run a baseline and save its receipt. Record the input, source, evaluated window or population, and value. A value without the evaluated input is not enough evidence.
Change one input only. Pick a second valid value that should exercise a different window or population. Confirm the receipt reflects that value. For a comparison metric, confirm both the current and prior windows moved.
Challenge a boundary. Use one safe edge case: an empty window, a narrow segment, a month boundary, or a period with a known answer. The result should match the declared empty-state or owner-approved expectation—not quietly fall back to the baseline.
Record pass or stop. Equal outputs can be legitimate, but only when the receipts prove that distinct populations or windows were evaluated and the anchor supports equality. Otherwise, stop and route the evidence to the metric owner.

Copy this card into the review thread:

Metric and decision it will inform:
Metric owner:
Parameter under test: date / filter / segment / comparison period
Source-of-truth anchor:

Case 1 — baseline input:
Expected window or population:
Observed window or population and value:

Case 2 — one changed input:
Expected change:
Observed window or population and value:

Case 3 — boundary or known-answer input:
Expected behaviour:
Observed behaviour:

Decision: pass / stop
Evidence link:

Stop conditions. Stop if the receipt omits the evaluated input; changing the input leaves a hardcoded window or population in place; both sides of a comparison resolve to the same period; an empty or boundary case silently returns the baseline; or the result misses the owner-approved anchor. Do not explain an identical number as coincidence until the window and population evidence prove it.

Why this check exists. A 9 September certified-query audit found five week-on-week definitions that reused one date placeholder for every endpoint, so they always returned zero delta, plus a sixth that accepted a date while pivoting on two hardcoded months. All six executed and returned numbers. The broader testing principle is established in dbt’s unit-test guidance: validate SQL logic against controlled inputs and expected outputs, especially date math, window functions, edge cases, and high-criticality models.

Recompute the unit and order of magnitude

A query can honour every input and still return the wrong scale. A rate may lose useful precision during intermediate arithmetic; a money metric may apply the same unit conversion twice. Both can produce tidy, believable numbers.

Before a metric informs a launch, target, or revenue decision, reconstruct one representative slice:

Write the equation and units. Name the numerator, denominator, and output unit. For money, spell out each conversion—for example, paise → rupees → crore—instead of hiding it inside a label.
Recompute from components. Ask for the underlying counts or amounts and calculate the result independently. Use an owner-approved dashboard or raw aggregate when available; do not validate a generated answer by asking the same query to explain itself.
Inspect precision before display rounding. Keep intermediate values at sufficient precision and round only the final displayed result. If a supposedly variable rate collapses to a few repeated values, stop and inspect the arithmetic types.
Check magnitude through a second route. For a rate, divide the representative numerator by its denominator. For an amount, compare against a rough count × typical amount estimate. The routes need not match perfectly, but they must agree on unit and order of magnitude.
Record pass or stop. Save the components, conversion chain, independently recomputed value, reported value, and owner-approved tolerance. A plausible-looking answer without reconstructable arithmetic does not pass.

Copy this card into the review thread:

Metric and decision it will inform:
Metric owner:
Declared equation:
Numerator value and unit:
Denominator value and unit:
Output unit:
Conversion chain:

Independently recomputed value:
Reported value before display rounding:
Reported display value:
Second-route magnitude estimate:
Owner-approved tolerance:

Decision: pass / stop
Evidence link:

Stop conditions. Stop if an input or output unit is unknown; the same conversion appears twice; an intermediate result is rounded before the final calculation; the recomputed value and reported value miss the approved tolerance; or the second route disagrees by an order of magnitude. Do not repair the discrepancy by widening the tolerance after seeing the result.

Why this check exists. Merged self-serve-analytics #2490 executed certified queries against live Trino and found two independent scale failures. Decimal arithmetic compressed rates that should have varied—for example, Saved Card Use Rate displayed 0.0 instead of roughly 2.1–3.1%—while an extra money conversion understated two MCC metrics by exactly 100×. Execution and input sensitivity would not catch either defect; reconstructing components, units, and magnitude does. Trino’s decimal operators documentation explains why result precision and scale depend on the operand types.

Validate a redesign without cutting over

Some metrics now have two certified Trino queries: the legacy table that dashboards use and a rebuilt redesign table under validation. Analytics Agent keeps serving legacy by default. When it reports redesign_pair_available: true, you can compare both paths without changing the served answer. Served does not automatically mean correct: the legacy query may carry a known definition defect that the redesign is meant to repair.

Refresh before you validate. Run the catalog-change preflight above. Do not start the comparison until the refreshed Analytics Agent commands load and the normal metric receipt names the expected source.

Qualify the control before you compare. A delta tells you that two queries disagree; it does not tell you which query is right. Read the metric definition and both query intents with the domain owner, then classify the legacy path:

Legacy baseline	How to use it
Fit	Its population, grain, filters, and time semantics match the approved metric intent. Use it as the comparison control.
Caveated	It has an owner-confirmed limitation with a known effect. Record the caveat and expected direction or range before comparing.
Invalid	It contradicts the approved intent—for example, it counts successful attempts when the metric is meant to count all attempts. Keep it as the served reference, but do not make the redesign reproduce the defect. Validate both paths against an independent anchor and stop for owner review.

If the metric intent, domain owner, or legacy classification is missing, stop. More decimal places will not repair an undefined control.

Use this PM validation loop:

Ask the normal metric question first. Keep the metric, date range, filters, and breakdowns fixed. Save the legacy value and source table from the receipt, then record the approved intent and the legacy classification above.
Freeze one shared complete window. Record the latest whole business interval complete on each producing path, then use the earlier boundary as the comparison end. For daily metrics, if either path has only a partial “today,” end at the previous day that is complete on both. Run the exact same start and end on both paths; matching date text is not enough when refresh cutoffs differ.
Say compare redesign. Analytics Agent runs the registered legacy and redesign queries with the same inputs and presents the values and percentage delta side by side. If it says no redesign pair is registered, stop; do not invent a table swap.
Read the difference, not just the tick. A delta above 1% is marked ❌, but that is an investigation flag—not proof that redesign lost. A smaller delta can still matter for money, counts, or narrow segments. Check that both sides use the same grain, filters, frozen complete window, and business population. If legacy is caveated or invalid, compare the result with an owner-approved independent anchor such as a governed definition plus a raw-event count.
Trace freshness and coverage to the producer. A current timestamp on the final table may prove only that a downstream copy ran. Follow the metric receipt back through the serving table to the table or job that actually produces the data. Confirm that its available partitions cover the full consumer and comparison window—not only the latest day. Then compare at least one value distribution or decision-critical segment. Matching row counts can still hide wrong values after a join.
Record an approve-or-stop decision. Approve only the metric and window you checked. Attach the comparison receipt, baseline classification, independent anchor when needed, and any accepted owner-confirmed caveat. If redesign intentionally corrects legacy semantics, record the old defect and the owner’s approval instead of demanding parity. One green metric does not approve an entire domain.

use redesign is a cross-check, not a cutover. Its answer should remain labelled under validation. The final /ch-promote <domain> --redesign step belongs to the analytics/data owner after every metric in scope is green; PM validation supplies evidence, not production authority.

Copy this card into the validation thread:

Plugin refreshed and Claude Code restarted? yes / no
Metric:
Approved metric intent and population:
Domain owner:
Legacy baseline: fit / caveated / invalid
Known legacy caveat or defect:
Expected delta direction or range:
Independent anchor (required if legacy is invalid):
Date range and filters:
Legacy complete through:
Redesign complete through:
Shared comparison end (earlier complete boundary):
Partial current interval excluded? yes / no
Legacy table and value:
Redesign table and value:
Delta:
Same grain and frozen complete window? yes / no
Freshness recheck needed? yes / no
Producing table or job:
Latest producer timestamp:
Latest serving-table timestamp:
Producer coverage / required consumer window:
Value-distribution or decision-critical segment check:
Refresh owner:
Known caveat and owner:
Decision: approve / stop
Comparison receipt:

Stop conditions. Stop if the plugin was not refreshed, no registered pair exists, either query fails, the metric intent or domain owner is unknown, the legacy baseline is unclassified, an invalid legacy baseline has no independent anchor, the grain or filters differ, either producer’s complete-through boundary is unknown, the queries do not share one frozen complete window, the producing source or refresh owner is unknown, only the downstream copy has a current timestamp, producer coverage is shorter than the consumer window, matching row counts have no value-distribution or segment check, a freshness explanation is unverified, or the result conflicts with an owner-approved source of truth. Keep legacy as primary and route the evidence to the metric owner.

Why this path exists. The registered shadow → compare → promote contract shipped in self-serve-analytics #1926. The first Reporting rollout then asked a PM to run the comparison and sign off only when values match in #analytics-self-serve. A later 17-pair validation request made the plugin-refresh preflight explicit because the marketplace can leave the bundled metric catalog stale silently. On 1 September, all 68 payments-infra KAM metrics switched to redesign tables, and the cutover note warned users to update the plugin or keep reading the old catalog; automated catalog syncs landed in claude-plugins #1277 and #1278. That makes refresh a routine post-cutover check, not only a shadow-validation step. A 13 August investigation exposed the other freshness trap: a daily downstream load made roughly 22 metrics look current while their manually rebuilt source had not changed since 4 August. On 17 August, a Mid Market pair showed the control itself can be wrong: legacy counted only successful attempts while redesign counted all intended attempts. On 27 August, self-serve-analytics #2239 proved a one-day producer was feeding 30-day consumers: per-day row counts matched while a derived value silently changed. A same-day #ai-help recovery restored the latest date but stamped 13 backfilled days into two partitions. The repository now guards the producer window with a custom test—the same assertion pattern documented in dbt data tests. On 10 September, a 58-metric Rize validation request found one redesign reading roughly 1.2% low because both queries ended on “today” while legacy rebuilt at 12:15 and redesign at 08:00. Freshness belongs to the producing data, completeness belongs to the shared interval, coverage belongs to the full consumer window, and correctness belongs to the approved metric intent—not whichever query shipped first.

Ask, review, or contribute?

Use the smallest Analytics Agent workflow that matches the job:

Need an answer about an existing metric?       → /analytics-query
Need a health check on existing analytics?     → /analytics-review
Found a missing or incorrect metric definition? → contribute one governed metric

Contribution is different from asking a question. It changes the shared metric glossary and its certified query, so it belongs in a reviewed PR—not in a chat answer that disappears when the session closes.

Temporary stop — 30 July 2026. Do not start or merge a metric-catalog change with metric-catalog-builder. The released builder can produce incorrect YAML while the correctness fixes in self-serve-analytics #1908 await review: it can choose the wrong serving layer, strip required _dist / FINAL syntax, discover domains from a stale list, and miscount glossary-to-query parity. The Analytics Agent /analytics-update-catalog route is blocked on the same fix. Normal metric queries and reviews are unaffected; this stop applies only to catalog mutation.

Once the stop is lifted, start from a clean local clone of razorpay/self-serve-analytics, then run /analyst:metric-catalog-builder with no arguments. The skill walks one metric through the current seven-step add-or-modify path:

Bring a metric brief. Name the metric, product area/domain, description, source table, formula or query, unit, filters, and gotchas. If you cannot name the source and computation yet, use /analytics-query to investigate first.
Choose the discovered domain. Prefer an existing domain from the skill’s picker. Creating a new domain needs explicit owner confirmation; a similar-looking folder is not close enough.
Review ADD versus MODIFY. For an existing metric, inspect every old → new field. For a new metric, confirm the glossary location and certified-query location before files are written.
Require execution, behaviour, and scale checks. The source table must exist and the query must run in Trino or ClickHouse with LIMIT 1. A returned row proves execution only. Before calling the query GREEN, use the parameter check above for every date, filter, segment, or comparison input, then recompute one representative result. An empty result needs explicit confirmation; a failed query does not become “documentation only”—fix it before proceeding.
Keep the diff domain-scoped. The glossary term and certified query may change, plus the generated merged glossary. Unrelated domain cleanup belongs in another PR.
Approve the change summary. Confirm the metric, domain, serving layer, files, and sample value before the skill commits or opens a PR.
Wait for CI and human review. A generated PR is a proposal, not a live metric. Merge only after metadata validation passes and the owning reviewer agrees with the definition.

Copy this preflight card before you invoke the skill:

Metric name:
Product area / domain:
What it measures:
Source table:
Formula or query:
Unit:
Filters:
Gotchas:
Owner who can review the definition:

Stop conditions. Stop and resolve the gap if the source table is unknown, the query fails, the glossary and certified-query counts do not match, the diff reaches another domain, or no owner can review the meaning. The skill can validate SQL and scope; it cannot decide what the business metric ought to mean.

Why this path exists. The single-metric workflow, domain discovery, and scope-containment guardrails shipped in self-serve-analytics #1756, #1760, and #1788. Keep implementation detail in that repo-owned skill; use this card to choose the workflow and arrive prepared.

Slash

Surface type. Razorpay’s remote internal AI worker, invoked with @slash. It has a knowledge-first mode for understanding and an execution mode for scoped repo work. It is distinct from the Claude Code session running on your machine.

Default context. Your task, any repo scope you name, and the approved skills, plugins, and internal sources available to that Slash run. This is remote task context, not your local terminal state.

What it can see. Approved internal data and the remote repo or repos selected for the task. It cannot see uncommitted files on your laptop, and public-web access is not a safe default assumption.

What it can do. Research an internal flow, gather context before implementation, invoke approved skills/plugins, implement a scoped change, and raise a PR. Put the mode immediately after @slash and choose the smallest depth that can support the decision:

Need	Invocation	Search depth
A quick owner, repo, or known-fact lookup	`@slash --plan-fast <query>`	Curated knowledge only. Fastest, but not enough for a high-consequence conclusion.
A flow or policy explained with direct support	`@slash --plan <query>` or `@slash --discover <query>`	Curated knowledge plus one code-evidence round. This is the default.
A cross-service architecture, disputed fact, root cause, or claim that something does not exist	`@slash --plan-accurate <query>`	Deep multi-repo search. Slowest and most thorough.
A bounded implementation whose repo and acceptance criteria are already known	`@slash repo:<repo-name> <task>` or `@slash repos:<repo-a>,<repo-b> <task>`	Execution mode. Review the resulting PR normally.

Try the evidence-depth check. Before sending a knowledge-first query, finish this sentence: “I will use the answer to ___.” Then choose the receipt the decision needs:

If the answer will…	Require this receipt
orient you, without triggering a decision	the named curated source and its date;
shape a spec, workflow, or owner handoff	the source-of-truth system plus a direct document, code, or configuration citation;
diagnose a failure or assert absence	the direct error or runtime record, the authoritative registration/configuration source, and the boundaries of every search.

For the last case, make the evidence contract explicit:

@slash --plan-accurate <question>. Before concluding that anything is absent,
query its authoritative source directly, name every surface searched, and label
unqueried or inaccessible sources UNKNOWN.

Zero hits in one repo or log store prove only that the search returned zero hits. They do not prove “never registered,” “does not exist,” or “did not run.” If Slash cannot query the authoritative source, stop at UNKNOWN and ask for that source instead of turning missing evidence into a root cause.

What it cannot do. Inspect your local uncommitted state, provide a tight localhost edit-run-debug loop, or turn an opened PR into verified work. Claude Code remains the local belt path; Slash is the remote delegation path.

Common failure modes. Using fast mode for a cross-service or high-consequence claim. Treating zero search hits as proof of absence. Executing before the problem is understood. Omitting the repo scope. Assuming a remote run sees local changes. Treating the generated PR as reviewed. Match depth to the decision, preserve UNKNOWN when the source of truth is unavailable, and keep execution behind explicit scope and normal review evidence.

Close the loop with the task receipt

Slash finishes with more than an answer. Its footer reports the job cost, model, duration, Discover ID, execution-log link, and a rating prompt. Do not treat that footer as decoration: it is the receipt for deciding whether this task shape was useful enough to repeat.

Read it in this order:

Outcome first. Did the response answer the named question or produce the requested artifact? Check its important claims or diff before judging the run successful.
Time and cost second. Was the result worth the reported duration and cost? There is no universal “good” number. Compare repeated tasks of the same shape, not unrelated work or model names in isolation.
Trace when surprised. If the answer is unsupported, the run is unexpectedly slow or expensive, or the task fails, open the execution logs. Record the Discover ID when routing a follow-up so the run remains identifiable.
Change one thing before retrying. Narrow the question, source window, repo set, or success criterion. If the task needed understanding before action, move to --plan / --discover. Do not rerun the same broad request and hope the receipt becomes cheaper by optimism.

Copy this card into your work note or task thread:

SLASH TASK RECEIPT
Task and mode:
Scope (repos, sources, or time window):
Useful outcome:
Evidence checked:
Job cost / duration / model:
Discover ID / execution logs:
Decision: accept | clarify | rerun narrower | stop
One change before another run:

The cost is not a quality score. A slow investigation can still be valuable; a cheap wrong answer is still wrong. Use the rating prompt to record outcome quality, but keep verification separate.

Further reading: B.10 — Cost + observability at scale explains the wider outcome, cost, and trace model; the OpenTelemetry generative-AI semantic conventions show why model operations and usage belong in inspectable traces.

Belt relevance. Useful at every belt for research and scoping; useful from Yellow onward for bounded remote repo tasks. It complements rather than replaces the Claude Code + Compass belt workflow.

Cursor

Surface type. A VS Code-style IDE with an AI side panel, plus an integrated terminal in which Claude Code can run.

Default context. Open files and folders in the editor, terminal output, plus whichever AI provider you are connected to in the side panel.

What it can see. Whatever the IDE has open, plus the terminal session if you are running Claude Code inside it.

What it can do. Multi-file editing, search, IDE navigation, side-panel chat, and a hosted Claude Code session in the integrated terminal.

What it cannot do. Replace the policy and skill layer that Compass provides inside Claude Code. The Cursor side panel and Claude Code are separate sessions; what one knows, the other does not.

Common failure modes. Treating the side panel as Claude Code. Two sessions, two memories, two outputs — easy to get crossed.

Belt relevance. Optional comfort layer for any builder who prefers a graphical editor while running Claude Code in the integrated terminal.

Codex / non-Claude coding tools

Surface type. A coding-agent workspace outside the Claude Code + Compass path. Codex can inspect and edit a local workspace, but it does not automatically inherit Razorpay’s Claude-shaped skills, hooks, MCPs, or connector approvals.

Default context. The workspace or app session you open, plus whatever files and plugins that surface is allowed to access. Access is controlled separately and can change. Do not assume an earlier MyAccess request or workspace invite is still an active route; confirm the latest support guidance first.

What it can do. Bounded implementation, verification, and second opinions when support explicitly confirms access for the task. It is not a general answer to LiteLLM model limits: when Codex is unavailable, continue with Claude or an enabled GPT route through LiteLLM, or follow the Claude Team migration route if support has provisioned you there.

What it cannot do. Replace Claude Code as the belt path. It does not make Compass checks optional, and plugin access can still be blocked by org OAuth or security policy even after the base workspace works.

Common failure modes. Assuming a Codex plugin has the same connector approval as Claude Code. Treating Codex output as ready to ship without bringing it back through Claude Code, Compass, tests, and the normal PR review path.

Belt relevance. Optional secondary surface from Yellow Belt onward when access is confirmed. White Belt still establishes Claude Code + Compass because that is the certified program spine.

Decision flow

Before you open a tool, run this filter in your head:

If the work edits files in a repo, default to Claude Code.
If the work is “think with me,” default to Claude.ai.
If the work is visual ideation or a deck draft with design-system context, default to Claude Design.
If the work is non-code office workflow on a folder, default to Cowork.
If current enablement asks for hash, install it once, run rzh doctor, and use rzh status or rzh ui to inspect the local harness before opening a work session.
If the work is PM adoption instrumentation, install the PM tracer after Claude Code is GREEN and verify it with /tracing-doctor.
If the work is metric or SSA analysis, use Analytics Agent after its setup/onboarding flow instead of the retired querying-metrics habit.
If the work is internal research, use Slash knowledge-first mode. If it is a bounded remote repo task, give Slash the repo and acceptance criteria in execution mode.
If the work needs visual file navigation, host Claude Code inside Cursor’s terminal.
If support confirms Codex access for a bounded task, use it only for that scope and bring the result back through Claude Code before shipping.
If you cannot tell what shape of work it is, name the work in one sentence first; the right tool usually appears in the sentence.

Anti-patterns to avoid

The atlas exists because these patterns keep happening and keep costing time.

Drafting code in Claude.ai, pasting into a repo. Skips every guardrail Compass provides. Code that “looked clean” in chat lands in a PR with the wrong design-system component, the wrong prop names, or no test coverage. Always re-route through Claude Code before committing.

Treating Claude Design as the shipping path. Claude Design is excellent for seeing options quickly. It is not a repo-aware implementation environment, and it does not replace the Blade MCP or review evidence. Move from visual intent to Claude Code before changing source.

Asking Claude Code to do non-code synthesis. Treating it as a chat tool wastes its harness. If the task does not touch a file, a run, or a connector, do it in Claude.ai or Cowork.

Using the wrong Slash mode. Asking execution mode to “figure it out and ship” mixes discovery with code changes. Use knowledge-first mode until the repo, constraints, and success criteria are clear; then delegate the bounded implementation and review the PR normally.

Confusing instrumentation with capability. The PM tracer can make usage visible; it cannot make the work useful. More tokens do not mean better adoption.

Treating Analytics Agent as a raw database shortcut. Use the maintained SSA plugin flow. If access, setup, or native-Windows plumbing blocks you, route the issue instead of improvising credentials or shell wrappers.

Running two parallel sessions and hoping they synchronise. Cursor’s side panel and Claude Code in the terminal are different sessions. Pick one to drive a given task.

Treating Codex as a Compass clone. Codex may be approved for the coding task, but its plugins and connectors are governed separately. If a plugin auth fails, do not work around it by pasting sensitive data into the session. Route the plugin/access issue through the support path and keep shipping changes behind Claude Code + Compass review.

Sending sensitive data to the wrong surface. PII, secrets, customer-identifying records, and money-handling fragments belong in approved surfaces only. The safety brief in Prologue 0.11 and the redline cards in Appendix H are the canonical references.

Where to go next

For the first 60-second tour, read Prologue 0.5 — Meet your tools.
For setup and verification, read Appendix B — Environment Setup.
For reusable workflows, read Appendix C — Skills Library.
For the philosophy behind context and harness choices, read Appendix N.5 — Three pillars.
For the redlines that apply across surfaces, read Appendix H — Reference Cards.

The cards above are the canonical first-pass. Per-tool deep-dives expand here as the program collects enough usage signal to justify them.