tool-contract-firstlisted
Install: claude install-skill RICK-ORPHEN/agent-discipline-skills
# Read the tool's contract before you fix
> "This is what happens when you patch things on the fly. Analyse it properly, then fix and
> design." — the requester
## When to use
- Whenever you call an external tool (CLI / API / browser / git / SDK) **for the first time**
- **Before a second fix for the same bug** ← this is the real trigger
- Whenever you catch yourself thinking "it is probably this flag" / "probably this header"
- When you are writing a script a human will run
---
## 1. Before the second fix, stop adding conditions
**If the first fix missed, you did not guess wrong — you did not read the tool.**
The second attempt is not "add one more condition." It restarts at **reading the contract.**
Three things to read:
| | What to read |
|---|---|
| The tool itself | `--help`, **end to end.** Do not skip EXAMPLES or ARGUMENTS |
| Existing call sites | Is **somebody already calling this tool?** If so, their shape is the answer |
| The canonical config | Bucket names, project refs, URLs — **do not decide them yourself.** The config file is authoritative |
### A real record — the same trap three times in one day
- A storage `ls` failed. `2>/dev/null` had thrown the reason away, so all that could be
reported was "cannot read it"
- Adding an `--experimental` flag then made `ss:///bucket` return **the bucket itself as one
entry, by prefix match.** The help said "List objects by **path prefix**." **It had not
been read**
- Only on the third attempt did the real a