Distillation

Date: Sep 10, 2026

• 🔴 (15:55) Project property-testing convention: properties should always hold regardless of input; tests use fcAssert(property(...), { numRuns: DEFAULT_NUM_RUNS }), including symmetry and encode/decode round-trip properties.
• 🔴 (15:55) Project command architecture uses buildCommand() with docs, output, parameters, and an async generator func; output may define human, optional jsonTransform, and optional jsonExclude, while commands yield CommandOutput and may return a user hint.
• 🔴 (15:55) Project structure: src/bin.ts is the entry point; src/app.ts contains Stricli application setup; src/context.ts provides dependency injection; src/commands/ contains command groups and standalone commands; src/lib/ contains shared utilities including api/, db/, dsn/, and formatters/; src/types/ contains TypeScript types and Zod schemas; test/ mirrors src/ and includes unit, *.property.test.ts, *.model-based.test.ts, e2e/, fixtures/, and mocks/; ../../apps/cli-docs/ is the Astro + Starlight documentation site; script/ contains build/utility scripts; .cursor/rules/ contains Cursor AI rules; biome.jsonc is the lint configuration.
• 🔴 (15:55) Mutation create/delete commands use shared infrastructure from src/lib/mutate-command.ts, paralleling list-command.ts.
• 🔴 (15:55) src/lib/mutate-command.ts provides: isConfirmationBypassed(flags) for detecting --yes or --force; guardNonInteractive(flags) to throw in non-interactive mode without --yes; confirmByTyping(expected, message) for typed confirmation; requireExplicitTarget(parsed, entityType, usage) to block unsafe auto-detection; and spreadable DESTRUCTIVE_FLAGS / DESTRUCTIVE_ALIASES.
• 🔴 (15:55) Pagination hint convention: show -c prev when hasPreviousPage() returns true, show -c next when hasMore is true, and include both nextCursor and hasPrev in the JSON envelope.
• 🔴 (15:55) Sort convention: use "date" rather than "time" for timestamp-based sorting; export sort types from the API layer, such as SpanSortValue from api/traces.ts, and import them into commands, matching issue list, trace list, and span list.
• 🔴 (15:55) Sentry API endpoints have differing project-filter mechanisms; never apply both filtering mechanisms simultaneously.
• 🔴 (15:55) Error-class convention: use ContextError when the user omitted a required value, such as no org/project; use ResolutionError when a user-provided value was not found, such as project 'cli'; use ValidationError for malformed input, such as an invalid hex ID.
• 🔴 (15:55) Database tests should create an isolated database using createIsolatedDbContext() and invoke cleanup() in a finally block to prevent test interference.
• 🔴 (15:55) Automated bug-fix PRs, including Cursor BugBot PRs, must follow project rules intended to prevent duplication and staleness after five overlapping PRs accumulated.