Interface Facts

---
name: interface-facts
description: Establishes a third-party CLI flag, API field, model, price or limit from the tool and live vendor docs. Use before code depends on it.
---
<!-- Generated by `basicly skills-build` from skill.yaml. Do not edit; edit the source. -->

# Interface Facts

Establish how a third-party interface behaves from evidence you fetch now. A model knows an interface only as it was at training time, and vendors change interfaces.

The skill covers CLI flags and output formats, API fields and endpoints, model ids, context windows, token accounting, prices, rate limits, config schemas and behaviour that changes with a version.

## Rules

- **An external interface fact is unverified until you fetch it.** A wrong fact about another vendor's interface gets committed as prose and believed for months.
- **Read our own code before our own prose.** A design document's summary of an interface is a claim about a claim.
- **Run the installed binary before you read the documentation.** The documentation describes a release. The binary on the path is the one that runs.
- **Record the version and the date with every fact.** A claim with no version cannot be checked again, only argued again.
- **Only the vendor's own host counts as a source.** An aggregator, a mirror or a summary site does not.
- **Never cache or commit fetched documentation.** The cache lands in a consumer tree, and the upstream licence is not ours to give.
- **Correct the stale document in place.** Two claims that disagree cost more than one wrong claim.

## Order of evidence

1. **Our own code that touches the interface.** An adapter, a parser or a hook was written against a real probe and is under test.
2. **The installed binary.** Use `--help`, `--version`, `--dry-run`, or an invalid flag whose error names the valid set. For a default behaviour, run the command itself. A flag list does not show a default.
3. **The vendor's current documentation**, fetched now.
4. **The vendor's changelog**, which dates the change.
5. **The vendor's source or issue tracker**, which shows a documented feature that does not work.
6. **Third-party writing.** This is the weakest evidence and is never sufficient alone.

A landing page or a feature grid is marketing. A README is a claim.

## How to fetch

1. Limit the search to the vendor's host, so a third-party summary cannot rank above the source.
2. Fetch the specific page.
3. Ask a narrow question: the exact flag name, the exact field name, whether a machine-readable output mode exists.
4. Use browser tools only when a page needs JavaScript to render.

To find the documentation of uv, ruff, Claude Code, the Anthropic API, Codex, GitHub, Python or pytest, read [routes](references/routes.md). Probe a route before you quote it.

## State the claim precisely

- **Keep "the capability exists" apart from "we can reach it".** A documented feature can have no flag or output mode that our dispatch can read. A value that is not on stdout can still be readable from another place.
- **Write the claim at the precision the evidence supports.** "Has no config-file deny rule" is correct where "has no config file" is not. A vague note invites the next reader to remove what it justifies.

## Record the fact

Put the fact on the tracker record, with the version, the date and the URL:

```sh
basicly tracker write -- comments add <id> "verified <date> against <url> (<tool> <version>): ..."
```

When a repo document and the vendor disagree, the vendor decides what the interface does. The repo decides what we chose to do. Correct the document in place and name what refuted it.

When a value we depend on can be compared with data we already record, make the comparison a gate. A declared limit that recorded data contradicts is a defect that a machine can detect.