Surfaces

Surface detection

A release tells your customers what shipped. Surface detection is the other direction: it flags candidate changes to declared endpoints, database fields, and environment variables, with the source diff attached for review. Confirmed changes can then be routed to the teams you configured. Turn it on per repo under Repos → [repo] → Surfaces. It watches pushes to your default branch, so it runs whether or not you tag releases.

1. Declare what you expose

Yanib never guesses at your architecture. You describe it once in a .yanib.yml committed to the repo, reviewed in a PR like any other config and versioned with the thing it describes.

version: 1

  surfaces:
  - name: api-routes
    paths: ["app/api/**/route.ts"]
    detect: new_file
    owners: ["@acme/payments"]     # who owns it
    notify: ["#api-consumers"]     # which integrations hear about it
    docs: ["README.md"]            # what goes stale when it grows

detect picks the primitive: new_file fires when a file is added under paths, pattern fires when your regex matches an added line (capture group 1 becomes the identifier), and prisma_schema reads added models and fields straight off the diff. A repo with no config still works; you just get the defaults.

2. What counts as a change

Detection reads the diff, not the commit message, and not a model's opinion about what looks important. Each candidate lands as one of ADDED, CHANGED, RENAMED, DEPRECATED or REMOVED. The detector applies explicit path, file status, added-line, and rename rules to narrow what needs review; it does not prove downstream impact on its own.

Accuracy status. Structural behavior is covered by automated tests, but real-history accuracy across multiple repositories and live delivery is not yet independently verified. Treat detections as review candidates until the published calibration gates pass.

3. Who gets told

Owners resolve from the surface's owners: list first, and fall back to your CODEOWNERS file when it is absent, so most repos need no extra setup. Delivery goes to the integrations named in notify:, matched against the integration names you already set up in Integrations. When surface notifications are enabled, leaving notify: off uses every integration on the repo; naming channels narrows delivery to those integrations. A routed match is still a review candidate, not proof of impact.

4. Docs to review

A file listed under a surface's docs: becomes a review target when that surface matches and the commit did not update the file. With a separate opt-in, Yanib can open a pull request proposing an update. The PR never writes directly to your default branch and remains yours to edit, merge, or close.

5. You don't start from zero

When you connect a GitHub repo, Yanib reads a bounded slice of recent history (90 days by default) and imports structural matches as historical candidates before you have written a line of config. Those rows keep their original commit dates, are labeled as imported rather than human confirmed, and are never announced.

Review is the boundary. A structural match narrows the queue; it does not establish that a real downstream capability changed. Inspect the attached evidence before confirming or dismissing it.