Distillation

Date: Sep 9, 2026

• 🔴 (14:16) Repository instructions required shared ID validators from src/lib/hex-id.ts: validateHexId(value, label) for 32-character hex IDs with automatic UUID-dash stripping, validateSpanId(value) for 16-character hex span IDs with dash stripping, and validateTraceId(value) as a thin wrapper in src/lib/trace-id.ts; all normalize to lowercase and throw ValidationError for invalid input.
• 🔴 (14:16) Repository instructions required timestamp-based sorts to use "date" rather than "time" and required sort types such as SpanSortValue to be exported from the API layer and imported by commands.
• 🔴 (14:16) Repository instructions required descriptive positional placeholder values such as "org/project/trace-id", not "args".
• 🔴 (14:16) Repository instructions required all CLI errors to extend CliError from src/lib/errors.ts and required using EXIT.* constants when constructing errors; numeric exit codes must never be hardcoded outside errors.ts.
• 🔴 (14:16) Repository error hierarchy specified: CliError default exit code 1; HostScopeError 13; ApiError 30; AuthError 10–12 according to 'not_authenticated' | 'expired' | 'invalid'; ConfigError 20; OutputError 60; ContextError 22; ResolutionError 23; ValidationError 21; DeviceFlowError 51; SeerError 40–42 according to 'not_enabled' | 'no_budget' | 'ai_disabled'; TimeoutError 31; UpgradeError 50; and WizardError 61–64 by workflow step.
• 🔴 (14:16) Repository instructions distinguished error classes as follows: omitted required values use ContextError; supplied values that cannot be found use ResolutionError; malformed user input uses ValidationError.
• 🔴 (14:16) Repository instructions required ContextError.command to be a single-line CLI usage example, required alternatives: [] when defaults are irrelevant, and required " and " in plural resource text; the constructor rejects commands containing \n.
• 🔴 (14:16) Repository instructions stated pnpm run check:errors detects multiline ContextError commands and CliError instances with ad-hoc "Try:" strings.
• 🔴 (14:16) Repository instructions required unresolved user-provided names/titles to use fuzzyMatch() from src/lib/fuzzy.ts, showing at most 5 similar candidates; reference implementation is resolveDashboardId() in src/commands/dashboard/resolve.ts.
• 🔴 (14:16) Repository instructions prohibited silent catch blocks in src/: each catch must rethrow, log via log.debug() or log.warn(), or return a fallback while logging suppression via log.debug(); command files should use logger.withTag("command-name").
• 🔴 (14:16) Repository instructions stated the no-silent-catch Biome plugin at lint-rules/no-silent-catch.grit, registered in biome.jsonc, flags empty, comment-only, and return-only statement or .catch() forms; grandfathered catches use inline // biome-ignore lint/plugin: <reason>, and fixing one requires removing its suppression because --error-on-warnings makes orphaned suppressions fail as suppressions/unused.
• 🔴 (14:16) Repository instructions required wrong-entity-type auto-recovery when intent is unambiguous: 1. detect with helpers such as looksLikeIssueShortId(), SPAN_ID_RE, HEX_ID_RE, or non-hex checks; 2. resolve to the correct type; 3. warn through log.warn(); 4. return a hint toward the correct command. Ambiguous or impossible recovery must retain the error and add entity-aware suggestions.
• 🔴 (14:16) Repository instructions required all config operations to be asynchronous and awaited, including getAuthToken(), isAuthenticated(), and setAuthToken(token, expiresIn).
• 🔴 (14:16) Repository instructions required checking existing shared modules before creating any new src/lib/*.ts utility; if an existing module covers at least 80% of the need, it must be extended rather than creating a new file. Every new src/lib/**/*.ts file must begin with module-level JSDoc describing its purpose.
• 🔴 (14:16) Repository instructions identified shared modules to check first: duration and relative-time formatting in src/lib/formatters/time-utils.ts; hex-ID handling in src/lib/hex-id.ts; table/Markdown output in src/lib/formatters/; pagination in src/lib/db/pagination.ts and src/lib/list-command.ts; errors in src/lib/errors.ts; and search-query construction in src/lib/search-query.ts and src/lib/arg-parsing.ts.
• 🔴 (14:16) Repository instructions prohibited creating ad-hoc error types; error classes must come from src/lib/errors.ts.
• 🔴 (14:16) Repository import conventions required .js extensions for local ESM imports, external-package imports before local imports, and the type keyword for type-only imports.
• 🔴 (14:16) Repository list-command infrastructure distinguished: (1) src/lib/list-command.ts provides buildOrgListCommand, LIST_TARGET_POSITIONAL, LIST_JSON_FLAG, LIST_CURSOR_FLAG, and buildListLimitFlag for simple lists such as team list and repo list; (2) src/lib/org-list.ts provides dispatchOrgScopedList, OrgListConfig, and handlers for auto-detect, explicit, org-all, and project-search for complex commands such as project list and issue list; (3) standalone commands such as span list and trace list wire pagination directly in func().
• 🔴 (14:16) Repository instructions required list-command overrides to access narrowed fields through ctx.parsed; call resolveCursor() inside the org-all override; use "Project" as the ContextError resource for handleProjectSearch; and always set orgSlugMatchBehavior to "redirect" or "error" according to whether bare-org listing is appropriate.
• 🔴 (14:16) Repository instructions stated project filtering mechanisms must never be applied simultaneously: queryEvents uses project:<slug> in the query string through buildProjectQuery(); listReplays uses the projectSlugs parameter; and listIssuesPaginated uses either the project parameter or query string depending on mode.
• 🔴 (14:16) Repository instructions required new explore datasets to implement dataset-specific sort, query, fetch, field validation, and filtering behavior centrally in resolveDatasetConfig, rather than scattering if (dataset === ...) checks through func.
• 🔴 (14:16) Repository commenting policy preferred JSDoc over inline comments, required JSDoc for every exported function, class, and type plus important internals, and required type/interface fields to document meaning, units, allowed values, null semantics, and defaults.
• 🔴 (14:16) Repository instructions allowed inline comments only for non-expressible rationale, constraints, surprising edge cases, workarounds, or explanations of hardcoded values; comments that merely restate syntax and ASCII-art section dividers were prohibited.
• 🔴 (14:16) Repository test-file naming conventions specified *.property.test.ts in test/lib/, *.model-based.test.ts in test/lib/db/, unit *.test.ts files under test/ mirroring src/, and E2E *.test.ts files under test/e2e/.
• 🔴 (14:16) Repository test-isolation instructions required database/config-directory tests to use useTestConfigDir() from test/helpers.ts; it creates a unique temporary directory in beforeEach, points SENTRY_CONFIG_DIR to it, restores rather than deletes the environment variable in afterEach, closes the database, and cleans temporary files.
• 🔴 (14:16) Repository test-isolation instructions prohibited delete process.env.SENTRY_CONFIG_DIR, module-scope capture via const baseDir = process.env[CONFIG_DIR_ENV_VAR]!, and manual beforeEach/afterEach hooks that set or delete SENTRY_CONFIG_DIR; the environment variable must always be restored, never deleted, in afterEach.