Distillation

🔴 (09:31) Review working tree was at HEAD bbaa7b3b722b87f1bccfe84063269cbbcabe2741 on branch fix/agent-conversation-reference-root-cause, tracking deleted upstream origin/pr-1558 [gone]; the patch digest was dfcceb584e52de2d477015a74dfe42ac1e26e5f44ede4bf5da2afc9e343179d8. 🔴 (09:31) The uncommitted patch modified 32 files with 331 insertions and 170 deletions, spanning apps/cli-docs/src/fragments/commands/agent-conversation.md, generated skill Markdown, command/introspection libraries, agent-conversation commands, generators, and tests. 🔴 (09:31) packages/cli/src/lib/command.ts adds exported CommandExample = { readonly description: string; readonly command: string } and exported CommandDocumentation, extending native Stricli docs with optional readonly examples?: readonly CommandExample[]. 🔴 (09:31) prepareNativeDocs() in packages/cli/src/lib/command.ts strips structured examples before passing docs to Stricli and appends them to native fullDescription as Examples: lines formatted <command> # <description>; examples are prepared before enrichDocsWithSchema() so JSON field documentation remains at the end of native help. 🔴 (09:31) attachDocumentationMetadata() in packages/cli/src/lib/command.ts preserves the first customUsage entry as __primaryUsage and structured examples as __examples; buildCommand() now calls it with the original builderArgs.docs after constructing the Stricli command. 🔴 (09:31) packages/cli/src/lib/list-command.ts and packages/cli/src/lib/mutate-command.ts now accept the shared CommandDocumentation type; OrgListCommandDocs is now an alias of CommandDocumentation. 🔴 (09:31) packages/cli/src/lib/introspect.ts extends its internal Command shape with __examples?: readonly CommandExample[]. buildCommandInfo() prefers non-empty cmd.__examples, mapping each to # <description>\n<command>, over legacy document-derived examples. 🔴 (09:31) getPositionalString() in packages/cli/src/lib/introspect.ts now renders optional tuple parameters as [<placeholder>] and required tuple parameters as <placeholder>; unnamed parameters continue to use arg<index>. 🔴 (09:31) packages/cli/src/commands/agent-conversation/list.ts centralizes its optional organization positional in POSITIONAL, with tuple parameter { placeholder: "org", brief: "Organization slug", parse: String, optional: true }; USAGE_HINT is derived as sentry agent-conversation list ${getPositionalString(POSITIONAL)}, yielding sentry agent-conversation list [<org>]. 🔴 (09:31) agent-conversation list removed manual customUsage: ["[<org>]"]; introspection now derives [<org>] from the optional positional definition itself. Its unresolved-organization ContextError now uses the derived canonical usage hint. 🔴 (09:31) agent-conversation list command metadata defines 5 ordered canonical examples: 1. sentry agent-conversation list — “List recent agent conversations”; 2. sentry agent-conversation list my-org — “Explicit organization”; 3. sentry agent-conversation list --limit 50 --period 24h — “Show more, last 24 hours”; 4. sentry agent-conversation list -q "has:errors" — “Filter conversations”; 5. sentry agent-conversation list my-org -c next — “Paginate through results”. 🔴 (09:31) packages/cli/src/commands/agent-conversation/view.ts defines USAGE = "[<org>/]<conversation-id>" and derives USAGE_HINT = "sentry agent-conversation view [<org>/]<conversation-id>"; customUsage remains [USAGE] because the organization and conversation ID form one compound positional. 🔴 (09:31) agent-conversation view command metadata defines 3 ordered canonical examples: 1. sentry agent-conversation view conv-123 — “View full transcript (organization auto-detected)”; 2. sentry agent-conversation view my-org/conv-123 — “Explicit organization”; 3. sentry agent-conversation view my-org/conv-123 --json — “JSON output”. 🔴 (09:31) apps/cli-docs/src/fragments/commands/agent-conversation.md had all 36 lines removed, including its duplicated list/view examples, because those examples moved into command metadata. 🔴 (09:32) packages/cli/script/check-fragments.ts now skips fragment-coverage enforcement for a command when cmd.examples.length > 0; fragment coverage remains relevant for commands without metadata examples. 🔴 (09:32) packages/cli/script/generate-command-docs.ts now describes generated pages as combining auto-generated reference/examples from CLI metadata with hand-written guides/tips from fragments; fragments are the source of truth only for content that cannot live in command definitions. 🔴 (09:32) formatPositionalsTable() in packages/cli/script/generate-command-docs.ts now emits optional arguments as `[<name>]` and required arguments as `<name>`. 🔴 (09:32) packages/cli/script/generate-skill-markdown.ts adds exported formatCommandExamples(examples), returning an empty string for no examples or a Markdown section consisting of **Examples:**, a fenced bash block, and examples separated by blank lines. 🔴 (09:32) Both packages/cli/script/generate-command-docs.ts and packages/cli/script/generate-skill.ts now use the shared formatCommandExamples() helper, preventing divergent Markdown example rendering between docs and agent-skill output. 🔴 (09:32) Tests added in packages/cli/test/commands/agent-conversation/list.test.ts verify unresolved organization errors contain command: "sentry agent-conversation list [<org>]". 🔴 (09:32) Tests added in packages/cli/test/lib/command.test.ts verify buildCommand() retains structured command examples verbatim in __examples. 🔴 (09:32) packages/cli/test/lib/introspect.property.test.ts now generates an optional: boolean() for tuple positionals and verifies every parameter appears as either [<placeholder>] or <placeholder> according to that flag. 🔴 (09:32) packages/cli/test/lib/introspect.test.ts adds coverage that required-plus-optional tuple parameters render as <required> [<optional>], and that structured __examples override stale legacy examples while becoming # description\ncommand strings. 🔴 (09:32) packages/cli/test/script/generate-skill-markdown.test.ts replaces checks against the generated references/agent-conversation.md file with source-level introspection checks: list has no __primaryUsage, list positional is [<org>], view positional is [<org>/]<conversation-id>, structured examples are preserved, and formatCommandExamples() produces the expected fenced Bash section. 🔴 (09:33) Regenerated packages/cli/plugins/sentry-cli/skills/sentry-cli/SKILL.md and reference files corrected optional positional syntax for these commands: sentry org view [<org>]; sentry project list [<org/project>]; sentry project view [<org/project>]; sentry issue list [<org/project>]; sentry alert issues list [<org/project>]; sentry alert issues create [<target>]; sentry alert metrics list [<target>]; sentry cli completion [<shell>]; sentry cli upgrade [<version>]; sentry replay list [<org/project>]; sentry release list [<org/project>]; sentry release deploy <org/version> <environment> [<name>]; sentry repo list [<org/project>]; sentry team list [<org/project>]; sentry explore [<target>]; sentry feedback list [<org/project>]; sentry monitor list [<org/project>]; sentry trace list [<org/project>]; sentry trial list [<org>]; sentry trial start <name> [<org>]; and sentry init [<target>] [<directory>].