Distillation

Date: Sep 8, 2026

• 🔴 [enforced-async-handling] (21:41) Repository rule: “Always await promises in async functions - don't forget to use the return value”; use async/await rather than promise chains, handle async errors appropriately, and never use async functions as Promise executors.
• 🔴 [enforced-workflow] (21:41) Repository rule reaffirmed: always check package.json for the latest scripts before running project commands.
• 🔴 [enforced-dependency-policy] (21:41) Repository rule reaffirmed: packages must always be added with pnpm add -D <package> using the -D flag and placed in devDependencies, never dependencies.
• 🔴 [enforced-testing-invariant] (21:41) Property-based test assertions describe properties that “always hold regardless of input”; use fast-check with { numRuns: DEFAULT_NUM_RUNS }, where DEFAULT_NUM_RUNS is 50.
• 🔴 (21:41) Sentry CLI package metadata in packages/cli/package.json: package sentry, version 0.45.0-dev.0, Node engine >=20.0, development runtime Node >=22.15, package manager pnpm@10.11.0, and CLI binary sentry at ./dist/bin.cjs.
• 🔴 (21:41) Current branch is fix/agent-conversation-reference-root-cause; upstream origin/pr-1558 is gone. HEAD is commit bbaa7b3b722b87f1bccfe84063269cbbcabe2741 (bbaa7b3b7), message fix(docs): correct agent conversation argument syntax.
• 🔴 (21:41) Working tree has 14 modified files with 234 insertions and 95 deletions: apps/cli-docs/src/fragments/commands/agent-conversation.md, packages/cli/script/check-fragments.ts, packages/cli/script/generate-command-docs.ts, packages/cli/script/generate-skill-markdown.ts, packages/cli/script/generate-skill.ts, packages/cli/src/commands/agent-conversation/list.ts, packages/cli/src/commands/agent-conversation/view.ts, packages/cli/src/lib/command.ts, packages/cli/src/lib/introspect.ts, packages/cli/src/lib/list-command.ts, packages/cli/test/commands/agent-conversation/list.test.ts, packages/cli/test/lib/command.test.ts, packages/cli/test/lib/introspect.test.ts, and packages/cli/test/script/generate-skill-markdown.test.ts.
• 🔴 (21:41) Ultracite rules live at .cursor/rules/ultracite.mdc; commands are npx ultracite fix, npx ultracite check, and npx ultracite doctor. Production code must remove console.log, debugger, and alert; use descriptive Error objects, meaningful try-catch, and early returns.
• 🔴 (21:41) Modern TypeScript conventions: prefer unknown over any, as const for immutable literals, type narrowing over assertions, meaningful constants over magic numbers, arrow callbacks, for...of, optional chaining ?., nullish coalescing ??, template literals, destructuring, and const by default; use let only for reassignment and never var.
• 🔴 (21:41) Testing style rules: assertions belong inside it()/test(); async tests use async/await instead of done callbacks; committed tests must not contain .only or .skip; suites should avoid excessive nested describe blocks.
• 🔴 [enforced-runtime-policy] (21:41) Sentry CLI runs on Node.js, not Bun. Use node:* standard-library APIs and do not reintroduce Bun.*, bun:test, or bun CLI commands. File I/O uses await readFile()/await writeFile() from node:fs/promises; process execution uses spawn()/execFile() from node:child_process; prefer execFileSync(command, args) over string-based execSync() for user-controlled values.
• 🔴 [enforced-api-types] (21:41) When @sentry/api supplies API response types, import them directly rather than creating redundant Valibot schemas in src/types/sentry.ts.
• 🔴 [enforced-command-wrapper] (21:41) Stricli commands must import buildCommand from src/lib/command.ts via the appropriate relative .js path, never directly from @stricli/core; the wrapper adds telemetry, --json/--fields, and rendering. Commands use async *func(), yield new CommandOutput(data), and may return { hint }; do not add a custom json flag, branch on flags.json, or call stdout.write().
• 🔴 (21:41) Command files should contain only argument parsing, API orchestration/error handling/enrichment, and output dispatch. Formatting belongs in src/lib/formatters/<domain>.ts; files exceeding about 400 lines should extract formatter helpers. stderr.write() is prohibited in command files; use logger and CommandOutput.
• 🔴 [enforced-route-wrapper] (21:41) Route groups must import buildRouteMap from src/lib/route-map.ts, never directly from @stricli/core. Standard aliases are auto-injected: list → ls, view → show, delete → remove/rm, and create → new; do not manually duplicate these aliases.
• 🔴 (21:41) Standard positional [<org>/<project>/]<id> parsing uses parseSlashSeparatedArg and parseOrgProjectArg from src/lib/arg-parsing.ts. Required trace/span identifiers are positional rather than flags.
• 🔴 (21:41) Multiple required positional values are space-separated variadics and must not be split on commas; optional flag values are comma-separated using value.split(","), or flags.x.flatMap((v) => v.split(",")) for repeatable array flags. Every project create target is a name:platform pair, and project names cannot contain whitespace.
• 🔴 (21:41) Non-trivial human output uses the markdown pipeline with mdKvTable(), colorTag(), escapeMarkdownCell(), and renderMarkdown(). Do not embed raw muted()/chalk in output strings. isPlainOutput() precedence is SENTRY_PLAIN_OUTPUT > NO_COLOR > FORCE_COLOR for TTY > !isTTY.
• 🔴 [enforced-delete-safety] (21:41) Delete commands must use buildDeleteCommand() from src/lib/mutate-command.ts; it injects --yes/-y, --force/-f, and --dry-run/-n, and rejects non-interactive destructive execution unless --yes or --force is supplied, while dry-run bypasses the guard. Related helpers are isConfirmationBypassed(), guardNonInteractive(), confirmByTyping(), requireExplicitTarget(), DESTRUCTIVE_FLAGS, and DESTRUCTIVE_ALIASES.
• 🔴 (21:41) Create commands use DRY_RUN_FLAG and DRY_RUN_ALIASES from src/lib/mutate-command.ts for consistent dry-run support.
• 🔴 [enforced-pagination] (21:41) Paginated list commands use cursor-stack helpers buildPaginationContextKey(), resolveCursor(), advancePaginationState(), and hasPreviousPage() from src/lib/db/pagination.ts, plus paginationHint() from src/lib/list-command.ts. Supported cursor directions are next, prev, and first; last silently aliases next. JSON envelopes include both nextCursor and hasPrev.
• 🔴 (21:41) List-command abstraction preference order: 1. buildOrgListCommand for simple organization-scoped lists such as team/repo; 2. dispatchOrgScopedList with overrides for complex project/issue modes; 3. direct buildListCommand/manual pagination for trace/span/dashboard lists.
• 🔴 [enforced-api-limit] (21:41) For requested limits above API_MAX_PER_PAGE (100), list commands must auto-paginate, set perPage = Math.min(flags.limit, API_MAX_PER_PAGE), and loop until the limit is filled or pages are exhausted, bounded by MAX_PAGINATION_PAGES; never send an oversized per_page.
• 🔴 (21:41) Hex ID validation uses validateHexId(value, label) for 32-character trace/log IDs, validateSpanId(value) for 16-character span IDs, and validateTraceId(value) as a wrapper. Validators strip UUID dashes where applicable, normalize to lowercase, and throw ValidationError for malformed input.
• 🔴 (21:41) Timestamp-based sort values use "date", not "time"; sort types are exported from the API layer, such as SpanSortValue from api/traces.ts.
• 🔴 (21:41) Generated documentation workflow: pnpm run generate:docs runs generate:banner, generate:parser, generate:command-docs, generate:skill, and generate:docs-sections. Generated command docs are gitignored; generated skill files under plugins/sentry-cli/skills/sentry-cli/ are committed. Positional placeholders must be descriptive, such as "org/project/trace-id" rather than "args".
• 🔴 (21:41) Valibot schemas live alongside types in src/types/*.ts, types use InferOutput, and validation uses safeParse(). Type-only imports use import type, local ESM imports include .js, and imports are grouped external-first then local.
• 🔴 (21:41) Error selection convention: ContextError means a required value was omitted, ResolutionError means a provided value was not found, and ValidationError means malformed input. ContextError.command must be a single-line CLI usage example and its constructor rejects newline-containing commands; use alternatives: [] when defaults are irrelevant.
• 🔴 (21:41) Failed entity resolution should use fuzzyMatch() from src/lib/fuzzy.ts and show at most 5 similar candidates instead of listing every entity.
• 🔴 [enforced-catch-logging] (21:41) Production catch blocks must rethrow, log through log.debug()/log.warn(), or log before returning a fallback. The no-silent-catch Biome plugin at lint-rules/no-silent-catch.grit rejects empty, comment-only, and return-only catches; fixed grandfathered catches must remove their biome-ignore suppression because unused suppressions fail lint.
• 🔴 (21:41) Wrong entity types should auto-recover when intent is unambiguous: detect using looksLikeIssueShortId(), SPAN_ID_RE, HEX_ID_RE, or non-hex checks; resolve to the expected type; warn through log.warn(); and return a hint toward the correct command. Ambiguous/impossible recovery retains the error with entity-aware suggestions.
• 🔴 (21:41) Before adding a new src/lib/*.ts utility, extend an existing module if it covers at least 80% of the need. Every new src/lib/**/*.ts file requires module-level JSDoc.
• 🔴 (21:41) JSDoc is required for every exported function, class, and type and for important internals; type/interface fields document meaning, units, allowed values, null semantics, and defaults. Inline comments are reserved for non-obvious reasoning, constraints, workarounds, or hardcoded-value rationale; narrative comments and ASCII-art section dividers are prohibited.
• 🔴 [requested-property-tests] (21:41) Repository testing preference order is model-based tests for stateful systems, property-based tests for pure parsing/validation/transformation logic, then unit tests only for trivial behavior or properties that are difficult to express. When property tests cover an invariant, do not duplicate it with hardcoded unit cases; remove newly redundant unit tests.
• 🔴 [enforced-test-isolation] (21:41) Database/config tests must use useTestConfigDir() from test/helpers.ts. Tests must not delete process.env.SENTRY_CONFIG_DIR, capture it at module scope, or manually set/delete it in beforeEach/afterEach; the helper restores the prior environment value and cleans up isolated state.
• 🔴 (21:41) Organization-list overrides call resolveCursor() inside the "org-all" override, use "Project" for handleProjectSearch ContextError resources, and always set orgSlugMatchBehavior to "redirect" or "error" explicitly.
• 🔴 (21:41) Project filtering is endpoint-specific and mechanisms must not be combined: Discover/Events queryEvents uses project:<slug> in the query via buildProjectQuery(); replay index listReplays uses projectSlugs; issue index listIssuesPaginated uses either a project parameter or query depending on mode. New explore datasets centralize behavior in resolveDatasetConfig.
• 🔴 [enforced-pr-workflow] (21:41) Automated bug-fix PRs must: 1. search open/recent PRs and issues for the same file/symbol using gh pr list --state open --search "in:title <file-or-symbol>" and gh issue list --state all --search "<symbol>"; 2. comment on or extend existing work rather than duplicate it; 3. rebase onto current main and verify the bug still exists; 4. separate correctness fixes from subjective UX changes; 5. reuse shared helpers such as autoPaginate() and safeParseJson() rather than hand-rolling fixes.
• 🔴 (21:41) Current package scripts include pnpm run lint → biome check --no-errors-on-unmatched --error-on-warnings --max-diagnostics=none ./, pnpm run lint:fix → Biome write mode, pnpm run test:unit → generated docs/SDK plus Vitest coverage over test/lib test/commands test/types test/script, pnpm run test:e2e → Vitest over test/e2e, pnpm run check:fragments, pnpm run check:deps, pnpm run check:errors, pnpm run check:patches, pnpm run check:docs-sections, pnpm run check:env-coverage, and pnpm run check:stale-refs.