go-cobra-pflag-backtick-usage-placeholder
Done. Diagnosis verified end-to-end and the solution is written to ~/go-cobra-pflag-backtick-usage-placeholder.md.
Root cause: pflag's Flag.UnquoteUsage() (pflag v1.0.9, flag.go:587-617) treats the first backtick pair in a flag's usage string as a custom value-placeholder name. FlagUsagesWrapped (flag.go:723-726) then prints that name in the column after the flag and, because a non-empty name was found, suppresses the real type (string). So a description like (e.g. `forgejo --version`) was rendered as a bogus type column --forgejo-url forgejo --version, exactly as observed.
Fix: remove backticks from usage strings — plain text only:
- "URL of the Forgejo instance (e.g. `forgejo --version`)."
+ "URL of the Forgejo instance (e.g. forgejo --version)."
Verification (all run against cobra v1.10.2 + pflag v1.0.9, Go 1.26):
- Live repro at /tmp/repro — before: --forgejo-url forgejo --version bogus column, no string type; after: --forgejo-url string with the example inside the description.
- Regression test main_test.go asserts the real type column and that the snippet never leaks into a standalone column; it fails when the backticks are reintroduced and passes with the fix (go test ./... → ok).
- Direct check of pflag.UnquoteUsage: backticked usage returns name="forgejo --version" (the bug), plain usage returns name="string" (correct fallback).
Also included in the doc: a repo-wide sweep command to find any other backticked flag usages (rg -n '' -g '*.go'` filtered to flag registrations), and guidance on paired-vs-stray backticks (both are fixed by plain text).
# Evidence - Problem class: go-cobra-pflag-backtick-usage-placeholder - Model: openrouter/deepseek/deepseek-v4-flash-0731 - Solved: 2026-08-24T18:08:09.577Z - Verification: solution produced by pi in sandbox; see signatures.json
{"description": "pflag renders backticked text in a flag usage string as a placeholder name: --forgejo-url help showed a bogus type column because the description contained a backticked command. Fix: remove backticks from usage strings (plain text only). Verified live + judge tier2 PASS (helix GAP-042, tick #194, commit e0e6879).", "environment": "", "language": "", "model": "openrouter/deepseek/deepseek-v4-flash-0731", "problem_class": "go-cobra-pflag-backtick-usage-placeholder", "provider": "openrouter", "solved_at": "2026-08-24T18:08:09.577Z", "version": ""}Done. Diagnosis verified end-to-end and the solution is written to ~/go-cobra-pflag-backtick-usage-placeholder.md.
Root cause: pflag's Flag.UnquoteUsage() (pflag v1.0.9, flag.go:587-617) treats the first backtick pair in a flag's usage string as a custom value-placeholder name. FlagUsagesWrapped (flag.go:723-726) then prints that name in the column after the flag and, because a non-empty name was found, suppresses the real type (string). So a description like (e.g. `forgejo --version`) was rendered as a bogus type column --forgejo-url forgejo --version, exactly as observed.
Fix: remove backticks from usage strings — plain text only:
- "URL of the Forgejo instance (e.g. `forgejo --version`)."
+ "URL of the Forgejo instance (e.g. forgejo --version)."
Verification (all run against cobra v1.10.2 + pflag v1.0.9, Go 1.26):
- Live repro at /tmp/repro — before: --forgejo-url forgejo --version bogus column, no string type; after: --forgejo-url string with the example inside the description.
- Regression test main_test.go asserts the real type column and that the snippet never leaks into a standalone column; it fails when the backticks are reintroduced and passes with the fix (go test ./... → ok).
- Direct check of pflag.UnquoteUsage: backticked usage returns name="forgejo --version" (the bug), plain usage returns name="string" (correct fallback).
Also included in the doc: a repo-wide sweep command to find any other backticked flag usages (rg -n '' -g '*.go'` filtered to flag registrations), and guidance on paired-vs-stray backticks (both are fixed by plain text).
# Evidence - Problem class: go-cobra-pflag-backtick-usage-placeholder - Model: openrouter/deepseek/deepseek-v4-flash-0731 - Solved: 2026-08-24T18:08:09.577Z - Verification: solution produced by pi in sandbox; see signatures.json
{"description": "pflag renders backticked text in a flag usage string as a placeholder name: --forgejo-url help showed a bogus type column because the description contained a backticked command. Fix: remove backticks from usage strings (plain text only). Verified live + judge tier2 PASS (helix GAP-042, tick #194, commit e0e6879).", "environment": "", "language": "", "model": "openrouter/deepseek/deepseek-v4-flash-0731", "problem_class": "go-cobra-pflag-backtick-usage-placeholder", "provider": "openrouter", "solved_at": "2026-08-24T18:08:09.577Z", "version": ""}