work-backlog-item

<provided_arguments> $ARGUMENTS </provided_arguments>

<provided_arguments/> is free-text — flags, positional values, and/or a freetext suffix — either typed by a human invoking /dh:work-backlog-item ... directly, or already known to you when you are initiating this action yourself (e.g. a "capture a backlog item" or "groom/work item #N" decision you made in this session). In the self-initiated case you already know every field below directly — go straight to producing the coerced result; there is nothing in <provided_arguments/> you don't already know, and no reason to route it through anything else.

Coerce <provided_arguments/> to match this schema yourself, using the vocabulary below, then treat the result as <input/>: parse.schema.json.

Argument vocabulary:

• Route — the first positional word only, when it matches one of the keys registered in command-routes.json: create, groom, work, close, resolve, setup-github, progress, resume. Because only the first positional is ever checked, at most one route keyword can ever be found in a single invocation — there is no such thing as a "two routes" conflict. The same word appearing later (e.g. inside a title) is not a route. No match on the first positional → route is title_substring (positionals or freetext remain) or none (nothing at all — no flags, no positionals, no freetext).
• item_ref discriminator — any positional matching #N, bare digits, or a GitHub issue URL (https://github.com/{owner}/{repo}/issues/N) → normalize to #N (keep a URL verbatim). Checked across all positionals, not just the first — including one embedded inside an otherwise-ordinary title (verified: Fix bug on line 42 → {"route":"issue","item_ref":"#42","user_text":"Fix bug on line"} — the "42" is consumed as item_ref and removed from user_text, and route becomes issue rather than title_substring; be alert to this when a title happens to end in a number). When it is the only discriminator found (no registry route word present), route is the literal string issue — not title_substring — and no reference key is set (verified: #42 alone → {"mode":"interactive","route":"issue","item_ref":"#42"}). A route word and one item_ref may both be present (e.g. groom #50, close #42) — that is route + item_ref together (registry route wins as route, reference is set per the route table above), not a conflict. Two or more item_ref discriminators in one invocation (e.g. close #42 #55) is the one real conflict case — ask the user to disambiguate rather than picking one.
• Freetext delimiter — --, or a bare —/– (em/en dash — a mobile-autocorrect artifact; normalize a leading —/– on any token to --). Everything after the delimiter is user_text verbatim, regardless of content (quotes, code, punctuation — do not further tokenize it). No delimiter → user_text is whatever positionals remain after removing the route/item_ref tokens, space-joined. Exception when flags.quick is present: do not apply this delimiter rule — positionals before a -- are otherwise discarded (captured nowhere, since they don't match item_ref's pattern), which would silently drop part of the supplied request. Still remove recognized flags and their values first (per the Flags rule below — e.g. --quick --auto Fix login strips --auto, not just its own name), and still apply the item_ref discriminator only when it consumes the entire remaining text (e.g. --quick #42 alone → item_ref="#42", nothing left for user_text) — a discriminator match embedded in a longer request (e.g. --quick #42 fails on SSO) does not fire, since the surrounding text is exactly what quick/start.md Step 1 needs to derive title/observations from. After flags and a whole-text-only item_ref are handled, set user_text to whatever remains verbatim (any embedded -- is literal text, not a delimiter). Step 1 derives its own title and observations from that raw text — it is not pre-split here.
• Flags — --force, --auto, --quick (boolean, no value). mode is auto only when --auto is present, otherwise interactive.
• --help/-h present → show usage (this vocabulary plus argument-hint in the frontmatter) and stop; do not route.