Distillation

Date: September 9, 2026

• 🔴 (23:09) User stated extractFlags() always returns exactly one FlagInfo per input entry.
• 🔴 (23:09) User stated tuple positionals from getPositionalString() always produce angle-bracket placeholders; required parameters use <placeholder>, optional parameters use [<placeholder>], and an absent placeholder falls back to arg${index}.
• 🔴 (23:09) User stated array positionals from getPositionalString() always include an ellipsis (...).
• 🔴 (23:09) User stated project-create platform values must always be attached to the name with : and must never use the space-separated form; canonical syntax includes sentry project create [<org>/]<name>:<platform>..., while sentry project create my-new-app javascript-nextjs is invalid documentation output.
• 🔴 (23:09) User stated extractAllRoutes() never includes hidden entries.
• 🟡 (23:09) Tests for packages/cli/src/commands/agent-conversation/list.ts verify organization resolution from either the positional organization or resolveOrg() when omitted, and verify resolution errors use canonical command usage sentry agent-conversation list [<org>].
• 🟡 (23:09) buildCommand() now retains structured docs.examples on command introspection metadata via __examples; a test preserves { description: "Select an organization explicitly", command: "sentry thing list my-org" }.
• 🟡 (23:09) Generated command documentation now renders introspected examples through formatCommandExamples(cmd.examples). The examples section uses **Examples:**, a fenced bash block, and blank lines between examples.
• 🟡 (23:09) Generated skill/reference content filters command flags through getVisibleFlags(cmd), excluding hidden flags and names in GLOBAL_FLAG_NAMES; visible flags are emitted under **Flags:** using formatFlag(flag, cmd.aliases).
• 🟡 (23:09) Flag documentation syntax uses --${flag.name}, optionally prefixed by -${alias}, ; non-variadic parsed/enum flags append <${flag.name}>, while variadic flags append <${flag.name}>....
• 🟡 (23:09) Command headings combine cmd.path with cmd.positional when present, producing ### \${signature}``; commands without positional arguments retain an empty positional string.
• 🟡 (23:09) Documentation generation imports formatCommandExamples from ./generate-skill-markdown.js, allowing the same structured command examples to be used across generated docs and skill markdown.
• 🟡 (23:09) extractCommandPathFromHeading() parses generated command headings with COMMAND_HEADING_RE and prefixes a matched route with sentry .
• 🟡 (23:09) The skill-generation bootstrap creates src/generated/skill-content.ts on a fresh checkout, including src/generated/ recursively, with stub content export const SKILL_FILES: ReadonlyMap<string, string> = new Map();\n before dynamically importing the route tree.
• 🟡 (23:09) Fragment validation inspects Stricli route maps by object identity to determine a route’s default command: findDefaultInRouteMap() compares getDefaultCommand() with every getAllEntries() target and returns the matching entry’s original name; getDefaultCommandName() applies this to a named top-level route.