docs(skill): review follow-ups — gotcha-table consistency, stale D2 note, example naming

Devin caught the gotchas table still advising the tighten-in-follow-up
recipe this PR corrects elsewhere; the D2 note claiming deletes
inline-commit (staged since 0.8.0 — the rule is a deliberate boundary,
not an implementation gap); and the undirected example describing
`Related` while traversing `<issueRelated>` (text now names
`IssueRelated` per the PascalCase->lowerCamelCase convention).
This commit is contained in:
aaltshuler 2026-07-07 01:43:49 +03:00 committed by Andrew Altshuler
parent 7eb8a4b562
commit b92be13bc6
2 changed files with 3 additions and 3 deletions

View file

@ -377,7 +377,7 @@ These are the traps most likely to bite. Scan this table before debugging any pa
| `load --mode merge` after `@embed` source change | stale embeddings | `omnigraph embed --reembed_all` or `load --mode overwrite` |
| `schema apply` with feature branches open | rejected | Merge or delete branches first |
| `nearest(...)` / `bm25(...)` / `rrf(...)` without `limit` | compile error | Add `limit N` |
| Adding non-nullable property without backfill | unsupported migration | Make optional → backfill → tighten in follow-up apply |
| Adding non-nullable property without backfill | unsupported migration | Make optional → backfill; keep it optional (tightening `T?``T` is refused, OG-MF-106) |
| `omnigraph init --json` | `unexpected argument --json` | `init` doesn't support `--json`; drop the flag |
| `omnigraph init` on an already-initialized URI | `AlreadyInitialized` error (v0.6.0+) | `--force` to re-init (skips the schema preflight; does **not** purge data) |
| `schema apply` dropping a property/type | soft-dropped or rejected (no data loss) | add `--allow-data-loss` to actually drop the column |

View file

@ -117,7 +117,7 @@ query employees_of($company: String) {
### Undirected traversal (omnigraph >= 0.8.1)
For symmetric relations (same-endpoint-type edges like `Related: Issue -> Issue`),
For symmetric relations (same-endpoint-type edges like `IssueRelated: Issue -> Issue`),
angle brackets match the edge in **either direction**, deduplicated — one
pattern replaces querying both directions and merging:
@ -291,7 +291,7 @@ query add_and_link($slug: String, $pattern: String, $createdAt: DateTime, $updat
There's no `upsert` keyword at the query level — use `load --mode merge` for bulk upsert.
> **Insert/update-only OR delete-only (the D₂ rule).** A single mutation query may contain inserts and updates, **or** deletes — never both. Mixing a `delete` with an `insert`/`update` in the same query is rejected at parse time. (Inserts/updates go through a staged two-phase publish; deletes inline-commit — omnigraph doesn't yet use Lance's two-phase delete API (it shipped in Lance 7.0.0 but isn't wired in) — so they can't share one atomic statement.) Split a delete-then-insert into two separate mutations.
> **Insert/update-only OR delete-only (the D₂ rule).** A single mutation query may contain inserts and updates, **or** deletes — never both. Mixing a `delete` with an `insert`/`update` in the same query is rejected at parse time. (Deletes stage through the same two-phase publish as inserts/updates since 0.8.0; the D₂ split is a deliberate semantic boundary — one mutation query is constructive XOR destructive, keeping read-your-writes unambiguous — not an implementation gap.) Split a delete-then-insert into two separate mutations.
### Date and DateTime values