jbr870/devwork-skills

Fork 0

glab-cli: quick reference misses two observed traps (api --field :param substitution; ci list -b misparse) #31

New issue

Closed

opened 2026-08-13 11:18:37 +00:00 by jbr870 · 1 comment

jbr870 commented

2026-08-13 11:18:37 +00:00

Owner

Observation

The glab-cli quick-reference exists to prevent flag mistakes, but two traps observed in real runs are missing from it:

glab api --field substitutes :param path-variable syntax inside payload text, corrupting bodies that legitimately contain API route strings (verity-slot3-113-resume, 08:52:38: PREQ bodies with routes like /api/:id were rewritten). The quick-ref should say when to use --raw-field/--input instead.
glab ci list -b <branch> parses the value as a date, not a branch (verity-main-4c283a2c); the correct flag form is absent from the quick-ref tables.

Recurrence

2 independent runs, one trap each; both are the exact class of mistake the quick-reference section declares it prevents.

Hypothesis

Add both rows to the quick-reference tables. Per the #17 precedent (@hapi/lab row), confirm each against a real glab first rather than trusting the run reports' recollection of the fix.

Suggested lane

meta-amend, gated on confirmation against a live glab.

Filed by /meta-retrospective 2026-08-13.

## Observation The glab-cli quick-reference exists to prevent flag mistakes, but two traps observed in real runs are missing from it: 1. `glab api --field` substitutes `:param` path-variable syntax *inside payload text*, corrupting bodies that legitimately contain API route strings (verity-slot3-113-resume, 08:52:38: PREQ bodies with routes like `/api/:id` were rewritten). The quick-ref should say when to use `--raw-field`/`--input` instead. 2. `glab ci list -b <branch>` parses the value as a date, not a branch (verity-main-4c283a2c); the correct flag form is absent from the quick-ref tables. ## Recurrence 2 independent runs, one trap each; both are the exact class of mistake the quick-reference section declares it prevents. ## Hypothesis Add both rows to the quick-reference tables. Per the #17 precedent (@hapi/lab row), confirm each against a real glab first rather than trusting the run reports' recollection of the fix. ## Suggested lane meta-amend, gated on confirmation against a live glab. *Filed by /meta-retrospective 2026-08-13.*

jbr870 added the

component:adapters

type:docs

labels

2026-08-13 11:18:37 +00:00

jbr870 referenced this issue

2026-08-13 11:20:03 +00:00

Slow loop: periodic process review (drains devwork learnings, defer-rot, process-quality trend, conformance census) #10

jbr870 added the

priority:low

labels

2026-08-13 12:49:29 +00:00

jbr870 commented

2026-08-19 13:54:14 +00:00

Author

Owner

/meta-amend outcome — amended, closing

Finding verified at HEAD (d976759 + the post-cutover commits). Both traps still held, and both
were confirmed against a live glab on the dev machine (1.110.0, 1797d215) per the #17
precedent rather than taken from the run reports' recollection:

glab api --help documents, for --field: "Placeholder values :namespace, :repo, and
:branch are populated with values from the repository of the current directory" — i.e. the
substitution applies to values, not only to the endpoint. The quick reference presented
placeholders as an endpoint feature (- Supports placeholders: :namespace, :repo, :branch),
which is exactly the reading that let a PREQ body carrying route strings go through --field.
glab ci list --help confirms -b is --updated-before ("Expected in ISO 8601 format"), and
the branch filter is -r/--ref.

One correction to the issue's wording: the observation cites a route like /api/:id, but
glab 1.110.0's documented field-value placeholder set is :namespace, :repo, :branch — :id
is an endpoint-only placeholder. The amendment therefore states the verified set and gives the
conservative rule (route any body containing a colon-prefixed segment through --raw-field/--input),
which covers the observed corruption either way.

Amendment — plugin/skills/glab-cli/SKILL.md, commit ee15687:

Key gotchas: new bullet that --field/-F substitutes those placeholders inside values, with
the --raw-field/-f or --input escape.
Key gotchas: new bullet that ci list -b is a date, not a branch — branch is --ref/-r, and
ci view/ci trace do take --branch, which is where the reflex comes from.
api section: the placeholder line now says endpoint and --field values.

No flag table changed: both tables already carried the correct rows (--ref | -r,
--updated-before | -b). The defect was the missing warning, so the minimal fix is a warning.

Gate: scripts/lint-conventions.sh clean — 114 helper scripts, 689 shell-fence lines,
199 files under plugin/skills/.

Desk-check (both originating scenarios): an orchestrator consulting the gotchas before composing
glab api ... --field description=<PREQ text with routes> now reads the substitution warning and its
escape, so verity-slot3-113-resume's corrupted body does not recur; one reaching for a branch filter
on ci list is told -b is a date and pointed at -r, so verity-main-4c283a2c does not recur. Both
are clear yeses. Desk-check only — the real proof is the next glab-project dogfood run.

Context: ran as UAT Scenario 6 of #50 (one /meta-amend cycle, AC-5c) — post-cutover, plugin
form loaded, meta lane invoked by its bare name from the repo-local .claude/skills/. The helper
root resolved from git as the lane requires.

## /meta-amend outcome — amended, closing **Finding verified at HEAD** (d976759 + the post-cutover commits). Both traps still held, and both were confirmed against a live `glab` on the dev machine (**1.110.0**, `1797d215`) per the #17 precedent rather than taken from the run reports' recollection: 1. `glab api --help` documents, for `--field`: *"Placeholder values `:namespace`, `:repo`, and `:branch` are populated with values from the repository of the current directory"* — i.e. the substitution applies to **values**, not only to the endpoint. The quick reference presented placeholders as an endpoint feature (`- Supports placeholders: :namespace, :repo, :branch`), which is exactly the reading that let a PREQ body carrying route strings go through `--field`. 2. `glab ci list --help` confirms `-b` is `--updated-before` ("Expected in ISO 8601 format"), and the branch filter is `-r`/`--ref`. **One correction to the issue's wording:** the observation cites a route like `/api/:id`, but glab 1.110.0's documented field-value placeholder set is `:namespace`, `:repo`, `:branch` — `:id` is an *endpoint*-only placeholder. The amendment therefore states the verified set and gives the conservative rule (route any body containing a colon-prefixed segment through `--raw-field`/`--input`), which covers the observed corruption either way. **Amendment** — `plugin/skills/glab-cli/SKILL.md`, commit **ee15687**: - Key gotchas: new bullet that `--field`/`-F` substitutes those placeholders **inside values**, with the `--raw-field`/`-f` or `--input` escape. - Key gotchas: new bullet that `ci list -b` is a date, not a branch — branch is `--ref`/`-r`, and `ci view`/`ci trace` do take `--branch`, which is where the reflex comes from. - `api` section: the placeholder line now says endpoint **and** `--field` values. No flag table changed: both tables already carried the correct rows (`--ref | -r`, `--updated-before | -b`). The defect was the missing warning, so the minimal fix is a warning. **Gate:** `scripts/lint-conventions.sh` clean — 114 helper scripts, 689 shell-fence lines, 199 files under `plugin/skills/`. **Desk-check** (both originating scenarios): an orchestrator consulting the gotchas before composing `glab api ... --field description=<PREQ text with routes>` now reads the substitution warning and its escape, so verity-slot3-113-resume's corrupted body does not recur; one reaching for a branch filter on `ci list` is told `-b` is a date and pointed at `-r`, so verity-main-4c283a2c does not recur. Both are clear yeses. Desk-check only — the real proof is the next glab-project dogfood run. **Context:** ran as UAT Scenario 6 of #50 (one `/meta-amend` cycle, AC-5c) — post-cutover, plugin form loaded, meta lane invoked by its bare name from the repo-local `.claude/skills/`. The helper root resolved from git as the lane requires.

jbr870 closed this issue

2026-08-19 13:54:20 +00:00

jbr870 referenced this issue from a commit

2026-08-22 13:00:55 +00:00

glab-cli: name the two observed quick-reference traps

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

jbr870/devwork-skills#31

No description provided.

Rows
Columns