Distillation

Date: Sep 9, 2026

• 🔴 (16:16) User directive: Always load repo-setup before situation skills. Skills live under .agents/skills/, generated from canonical skills/ by scripts/sync-skills.mjs.
• 🔴 (16:16) User directive: Always check package.json for the latest scripts. Run commands from packages/cli, or from the repository root via pnpm --filter sentry run <script>.
• 🔴 (16:16) User directive: All packages must be added to devDependencies, never dependencies, because everything is bundled with esbuild and CI enforces this via pnpm run check:deps.
• 🔴 (16:16) User directive: Always add packages using pnpm add -D <package> with the -D flag.
• 🔴 (16:16) User stated that when @sentry/api provides response types, import them directly rather than creating redundant Valibot schemas in src/types/sentry.ts.
• 🔴 (16:16) User stated Sentry CLI runs on Node.js and was migrated from Bun; use node:* standard-library APIs and do not reintroduce Bun.*, bun:test, or bun CLI commands.
• 🔴 (16:16) User stated shell execution involving user-controlled values should prefer execFileSync with array arguments over string-based execSync to avoid shell injection.
• 🔴 (16:16) User stated CLI commands must import buildCommand from ../../lib/command.js, never directly from @stricli/core; the wrapper adds telemetry, --json/--fields, and output rendering. Command functions are async *func() generators that yield new CommandOutput(data) and may return { hint }; commands must not add their own json flag, call stdout.write(), or branch on flags.json.
• 🔴 (16:16) User stated route groups must import buildRouteMap from ../../lib/route-map.js, never directly from @stricli/core. Standard aliases are auto-generated as list → ls, view → show, delete → remove/rm, and create → new; these aliases must not be manually duplicated.
• 🔴 (16:16) User stated required multiple positional arguments are space-separated variadics and must not be comma-split, while optional multi-value flags are comma-separated using value.split(",") or flags.x.flatMap((v) => v.split(",")).
• 🔴 (16:16) User stated formatting/rendering belongs in src/lib/formatters/<domain>.ts; command files should focus on argument parsing, API orchestration, and output dispatch. If a command file exceeds approximately 400 lines, extract formatting helpers.
• 🔴 (16:16) User stated all non-trivial human output must use the markdown rendering pipeline with helpers such as mdKvTable(), colorTag(), escapeMarkdownCell(), and renderMarkdown(); raw muted()/chalk must not appear in output strings.
• 🔴 (16:16) User stated delete commands must use buildDeleteCommand() from src/lib/mutate-command.ts, which auto-injects --yes, --force, and --dry-run with -y, -f, and -n; create commands should use DRY_RUN_FLAG and DRY_RUN_ALIASES.
• 🔴 (16:16) User stated all paginated list commands must use the shared bidirectional cursor-stack infrastructure supporting -c next, -c prev, and -c first; "last" is a silent alias for "next". Navigation hints must use paginationHint() from src/lib/list-command.ts, not manually assembled navParts.
• 🔴 (16:16) User stated list-command abstractions should use the highest fitting level in this order: 1. buildOrgListCommand for fully automatic org-scoped lists, 2. dispatchOrgScopedList with overrides, 3. buildListCommand with manual pagination.
• 🔴 (16:16) User stated that when --limit exceeds API_MAX_PER_PAGE (100), list commands must transparently fetch multiple pages, set perPage = Math.min(flags.limit, API_MAX_PER_PAGE), and continue until results.length >= limit or pages are exhausted.
• 🔴 (16:17) User directive: Never pass a per_page value larger than API_MAX_PER_PAGE to the API; the server silently caps oversized values, causing commands to return fewer items than requested.
• 🔴 (16:17) User stated shared ID validators are validateHexId(value, label) for 32-character hex trace/log IDs with automatic UUID-dash stripping, validateSpanId(value) for 16-character hex span IDs with dash stripping, and validateTraceId(value) as a thin wrapper around validateHexId; all normalize to lowercase and throw ValidationError for invalid input.
• 🔴 (16:17) User stated timestamp-based sorting must use "date", not "time", and sort types should be exported from the API layer, such as SpanSortValue from api/traces.ts.
• 🔴 (16:17) User stated command docs and skill files are generated by pnpm run generate:docs, which runs generate:command-docs then generate:skill; generation also runs automatically through dev, build, typecheck, and test.
• 🔴 (16:17) User stated generated command docs under docs/src/content/docs/commands/*.md are gitignored; handwritten command content belongs in docs/src/fragments/commands/; generated skills under plugins/sentry-cli/skills/sentry-cli/ are committed; pnpm run check:fragments validates fragment-to-route consistency.
• 🔴 (16:17) User stated CLI errors extend CliError from src/lib/errors.ts; use EXIT.* constants rather than hardcoded numeric exit codes outside errors.ts. Relevant mappings include ContextError → 22 for omitted context, ResolutionError → 23 for a provided value not found, and ValidationError → 21 for malformed input.
• 🔴 (16:17) User stated fuzzy resolution suggestions should use fuzzyMatch() from src/lib/fuzzy.ts and show at most 5 matches.
• 🔴 (16:17) User stated silent catch blocks are prohibited in src/; every catch must rethrow, log with log.debug()/log.warn(), or return a fallback while logging the suppression. Command files should use logger.withTag("command-name").
• 🟡 (16:17) Tool reported a modified worktree containing 35 files with 394 insertions and 157 deletions. Modified files: .github/workflows/pr-risk.yml; apps/cli-docs/src/fragments/commands/agent-conversation.md; packages/cli/plugins/sentry-cli/skills/sentry-cli/SKILL.md; references agent-conversation.md, alert.md, cli.md, explore.md, feedback.md, init.md, issue.md, monitor.md, org.md, project.md, release.md, replay.md, repo.md, team.md, trace.md, trial.md under packages/cli/plugins/sentry-cli/skills/sentry-cli/references/; scripts 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; source files 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/src/lib/mutate-command.ts; tests packages/cli/test/commands/agent-conversation/list.test.ts, packages/cli/test/commands/agent-conversation/view.test.ts, packages/cli/test/lib/command.test.ts, packages/cli/test/lib/introspect.property.test.ts, packages/cli/test/lib/introspect.test.ts, and packages/cli/test/script/generate-skill-markdown.test.ts.