./runcli build --spec-file spec.yaml --model claude
The root cause: the cobra CLI only registered --model and --spec-file flags and took the task/spec content as positional args, but README/help examples and the in-repo usage skill told users to use --task/--spec flags that never existed. Any user copy-pasting those examples got unknown flag: --task and exit 1.
The fix has three parts:
1. Source of truth — the CLI (unchanged, verified): flags are declared once; everything else is derived from running it.
// main.go — the actual CLI contract
var rootCmd = &cobra.Command{
Use: "runcli [task] [spec...]",
Args: cobra.MinimumNArgs(1), // task is positional, required
RunE: ...,
}
func init() {
rootCmd.Flags().StringVar(&model, "model", "", "model to run the task against")
rootCmd.Flags().StringVar(&specFile, "spec-file", "", "path to a spec file")
// NOTE: no --task, no --spec flags exist
}
2. README — replaced the invented --task/--spec examples with one unified, verified CLI Examples block:
# Run a task against the default model (positional arg)
./runcli "write tests"
# Run a task against a specific model
./runcli "write tests" --model gpt-4o
# Pass the spec as a second positional argument
./runcli build spec.yaml
# Drive the task from a spec file
./runcli build --spec-file spec.yaml --model claude
Plus a flag table documenting that --task and --spec do not exist.
3. In-repo usage skill pitfall updated to match:
```md
Built with `go build -o runcli .` (go1.26.0, cobra v1.10.2) and verified: **Bug reproduced (before fix):** ``` $ ./runcli --task "write tests" → Error: unknown flag: --task (exit 1) $ ./runcli --spec build.yaml → Error: unknown flag: --spec (exit 1) ``` **Fix verified — every documented example runs (all exit 0):** ``` $ ./runcli "write tests" → model=default task="write tests" $ ./runcli "write tests" --model gpt-4o → model=gpt-4o task="write tests" $ ./runcli build spec.yaml → model=default task="build" spec="spec.yaml" $ ./runcli build --spec-file spec.yaml --model claude → model=claude task="build" spec="build all binaries\n" ``` **Edge cases tested:** - `--help` output lists only `--model`/`--spec-file`; no phantom flags. - Missing `--spec-file` path → exit 1 with `read spec file: ...` error. - Zero positional args → exit 1 (`cobra.MinimumNArgs(1)`). - Old `--task`/`--spec` forms still correctly rejected. - `grep -rn` over fixed docs confirms `--task`/`--spec` appear only in "do not exist" / pitfall wording, never in example commands. The fix is committed as real history in `/tmp/cobra-docs-fix`: `c8fa86c` (repro) → `80ecde1` (fix docs + skill) → `93bfbe1` (ignore build artifact).
{"model": "deepseek-v4-flash", "problem_class": "go-cobra-docs-flag-mismatch", "result": "passed", "tests": 10}