rudder-profiles-debug

Name: rudder-profiles-debug
Author: rudderlabs

18stars0forks

How to install rudder-profiles-debug?

rudderlabs/rudder-agent-skills/rudder-profiles-debug

$npx -y skills add rudderlabs/rudder-agent-skills --skill rudder-profiles-debug

Installs into the current project.

Summary

Diagnoses RudderStack Profiles compile failures, run failures, and output-quality problems. Use when pb compile fails, pb run fails, identity stitching looks wrong, output quality regresses, or Profiles errors need structured recovery.

Files · 1

View on GitHub

SKILL.md

1	# RudderStack Profiles Debugging
2
3	Debug Profiles errors with a structured loop: classify, fix, validate, and stop before thrashing.
4
5	## Workflow
6
7	1. Classify the error — Match the error output against the classification table below.
8	2. Apply the smallest plausible fix — One change, then re-validate.
9	3. Re-run `pb compile` (for compile errors) or the precise recovery command (for run failures).
10	4. Escalate progressively — If the first fix doesn't work:
11	- 2nd attempt: consult `search_profiles_docs()` for relevant documentation.
12	- 3rd attempt: read documentation examples and reference files.
13	- 4th attempt: STOP — present all findings to the user and ask for guidance.
14	5. Never attempt more than 4 fix cycles without user input.
15
16	## Error Classification
17
18	\| Error Pattern \| Category \| First Action \|
19	\|---------------\|----------\|-------------\|
20	\| `unmarshal`, `field not found`, parser line/col \| YAML Structure \| Check `references/common-yaml-mistakes.md`; inspect the referenced YAML section \|
21	\| `id type X not found` \| Cross-File Reference \| Verify id_type names match between `pb_project.yaml` and `models/` files \|
22	\| `model X not found` \| Model Dependency \| Run `pb show models`; check `from:` paths and model names \|
23	\| `invalid identifier`, `column not found` \| SQL/Warehouse \| Call `describe_table()` to verify the column exists \|
24	\| `does not match time regex` \| CLI Usage \| Use ISO 8601 format: `YYYY-MM-DDTHH:MM:SSZ` \|
25	\| `schema_version not supported` \| Version Mismatch \| Run `pb version`; align `schema_version` with the binary, or `pb migrate auto --inplace` \|
26	\| `warehouse not initialized` / `no connection` from `run_query()` \| MCP Precondition \| Call `initialize_warehouse_connection(<connection_name>)` once before any `run_query()` — a hard requirement documented in the MCP tool \|
27	\| `baseline not found`, `checkpoint not found`, `material X (seq_no Y) not found` on an incremental run \| Incremental State \| `references/incremental-debugging.md` § Checkpoint & Baseline — distinguish mid-run crash (`--seq_no N`) from state drift (`--rebase_incremental`) \|
28	\| Incremental run completes but values are subtly wrong; a `merge:` var uses a window function \| Silent Incremental Corruption \| `references/incremental-debugging.md` § Window Functions — the most likely cause is an unsupported window function under `merge:` \|
29	\| nil-pointer / segfault during compile/run, `DeRef` in the trace \| DeRef Crash \| `references/incremental-debugging.md` § DeRef Crashes — usually a bad `pre_existing=true` with no baseline \|
30	\| `rpc error`, `ModuleNotFoundError` \| Python/RPC \| STOP — surface the exact error to the user immediately \|
31
32	Python/RPC errors are OUT OF SCOPE. Do not run `pip install`, modify venvs, or edit Python paths. Surface the exact error and escalate.
33
34	## Run Recovery — `--seq_no N` vs `--rebase_incremental`
35
36	Two failure modes, two different flags. Picking wrong keeps you failing:
37
38	\| Symptom \| Cause \| Recovery \|
39	\|---------\|-------\|----------\|
40	\| `pb run` crashed/aborted mid-sequence; a seq_no is partial \| Interrupted run (network, timeout, kill) \| `pb run --seq_no N` resumes from the failed sequence using the existing baseline \|
41	\| Incremental output diverges from discrete; `baseline not found`; stale materials \| State drifted (baseline from a stale seq_no, or a non-mergeable change snuck in) \| `pb run --rebase_incremental` discards the checkpoint and rebuilds the baseline from scratch \|
42
43	- Never resume a crashed run with plain `pb run` — extract the failed seq_no and use `--seq_no N`.
44	- Never use `--rebase_incremental` for a plain mid-run failure — you'll throw away good incremental progress.
45	- Use `pb compile` as the primary validation loop — fast, and catches most errors before a run.
46
47	See `references/incremental-debugging.md` for the full checkpoint/baseline triage.
48
49	## Output-Quality Debugging
50
51	When the run succeeds but the data looks wrong (these are profiles-mcp tools the agent calls, not `pb` CLI commands):
52
53	1. Call the profiles-mcp tool `initialize_warehouse_connection(<connection_name>)` once this session before any `run_query()` — required, or `run_query()` fails with "warehouse not initialized".
54	2. Call `get_profiles_output_details()` for output metadata.
55	3. Run targeted SQL for health metrics (see `references/post-run-sql-queries.md`):
56	- Stitching ratio: raw IDs vs stitched entities.
57	- Over-stitching: entities absorbing too many IDs.
58	- Feature NULL rates: data completeness per feature.
59	- Run-over-run comparison: entity count drift between seq_nos.
60	4. Compare against prior runs when available.
61	5. Recommend `pb audit id_stitcher` and `pb show i

People who liked this also viewed

6 picks

Type

rudder-profiles-debug

18stars0forks

View on GitHub

How to install rudder-profiles-debug?

rudderlabs/rudder-agent-skills/rudder-profiles-debug

$npx -y skills add rudderlabs/rudder-agent-skills --skill rudder-profiles-debug

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# RudderStack Profiles Debugging
2
3	Debug Profiles errors with a structured loop: classify, fix, validate, and stop before thrashing.
4
5	## Workflow
6
7	1. Classify the error — Match the error output against the classification table below.
8	2. Apply the smallest plausible fix — One change, then re-validate.
9	3. Re-run `pb compile` (for compile errors) or the precise recovery command (for run failures).
10	4. Escalate progressively — If the first fix doesn't work:
11	- 2nd attempt: consult `search_profiles_docs()` for relevant documentation.
12	- 3rd attempt: read documentation examples and reference files.
13	- 4th attempt: STOP — present all findings to the user and ask for guidance.
14	5. Never attempt more than 4 fix cycles without user input.
15
16	## Error Classification
17
18	\| Error Pattern \| Category \| First Action \|
19	\|---------------\|----------\|-------------\|
20	\| `unmarshal`, `field not found`, parser line/col \| YAML Structure \| Check `references/common-yaml-mistakes.md`; inspect the referenced YAML section \|
21	\| `id type X not found` \| Cross-File Reference \| Verify id_type names match between `pb_project.yaml` and `models/` files \|
22	\| `model X not found` \| Model Dependency \| Run `pb show models`; check `from:` paths and model names \|
23	\| `invalid identifier`, `column not found` \| SQL/Warehouse \| Call `describe_table()` to verify the column exists \|
24	\| `does not match time regex` \| CLI Usage \| Use ISO 8601 format: `YYYY-MM-DDTHH:MM:SSZ` \|
25	\| `schema_version not supported` \| Version Mismatch \| Run `pb version`; align `schema_version` with the binary, or `pb migrate auto --inplace` \|
26	\| `warehouse not initialized` / `no connection` from `run_query()` \| MCP Precondition \| Call `initialize_warehouse_connection(<connection_name>)` once before any `run_query()` — a hard requirement documented in the MCP tool \|
27	\| `baseline not found`, `checkpoint not found`, `material X (seq_no Y) not found` on an incremental run \| Incremental State \| `references/incremental-debugging.md` § Checkpoint & Baseline — distinguish mid-run crash (`--seq_no N`) from state drift (`--rebase_incremental`) \|
28	\| Incremental run completes but values are subtly wrong; a `merge:` var uses a window function \| Silent Incremental Corruption \| `references/incremental-debugging.md` § Window Functions — the most likely cause is an unsupported window function under `merge:` \|
29	\| nil-pointer / segfault during compile/run, `DeRef` in the trace \| DeRef Crash \| `references/incremental-debugging.md` § DeRef Crashes — usually a bad `pre_existing=true` with no baseline \|
30	\| `rpc error`, `ModuleNotFoundError` \| Python/RPC \| STOP — surface the exact error to the user immediately \|
31
32	Python/RPC errors are OUT OF SCOPE. Do not run `pip install`, modify venvs, or edit Python paths. Surface the exact error and escalate.
33
34	## Run Recovery — `--seq_no N` vs `--rebase_incremental`
35
36	Two failure modes, two different flags. Picking wrong keeps you failing:
37
38	\| Symptom \| Cause \| Recovery \|
39	\|---------\|-------\|----------\|
40	\| `pb run` crashed/aborted mid-sequence; a seq_no is partial \| Interrupted run (network, timeout, kill) \| `pb run --seq_no N` resumes from the failed sequence using the existing baseline \|
41	\| Incremental output diverges from discrete; `baseline not found`; stale materials \| State drifted (baseline from a stale seq_no, or a non-mergeable change snuck in) \| `pb run --rebase_incremental` discards the checkpoint and rebuilds the baseline from scratch \|
42
43	- Never resume a crashed run with plain `pb run` — extract the failed seq_no and use `--seq_no N`.
44	- Never use `--rebase_incremental` for a plain mid-run failure — you'll throw away good incremental progress.
45	- Use `pb compile` as the primary validation loop — fast, and catches most errors before a run.
46
47	See `references/incremental-debugging.md` for the full checkpoint/baseline triage.
48
49	## Output-Quality Debugging
50
51	When the run succeeds but the data looks wrong (these are profiles-mcp tools the agent calls, not `pb` CLI commands):
52
53	1. Call the profiles-mcp tool `initialize_warehouse_connection(<connection_name>)` once this session before any `run_query()` — required, or `run_query()` fails with "warehouse not initialized".
54	2. Call `get_profiles_output_details()` for output metadata.
55	3. Run targeted SQL for health metrics (see `references/post-run-sql-queries.md`):
56	- Stitching ratio: raw IDs vs stitched entities.
57	- Over-stitching: entities absorbing too many IDs.
58	- Feature NULL rates: data completeness per feature.
59	- Run-over-run comparison: entity count drift between seq_nos.
60	4. Compare against prior runs when available.
61	5. Recommend `pb audit id_stitcher` and `pb show i

People who liked this also viewed

6 picks

Type