Guides
Read it all before you buy.
Setup guides and worked examples for everything sold here, readable without an email address. If the guides don’t convince you, don’t buy the pack.
Document Ops
Session Discipline
Setup guides and worked examplesPublished on launch day.January 12, 2027
Session handoff example: the note beforeThe example file that ships with the session handoff skill. It reads fine, and two of its claims are guesses.example file
# Handoff — the search reindex EXAMPLE FIXTURE — the "before" half of the session-handoff worked example. It is a demonstration input, not a real handoff, and not a document to copy. Written by the session that got the reindex most of the way there. Picking this up should be straightforward; most of the hard parts are done. ## Where it stands The new analyzer is landed and the reindex runs clean on staging. It cut p99 query latency by about 40%, which is well past what the ticket asked for. The old analyzer is still wired up behind a flag, and we can drop it once the backfill finishes. Three of the twelve shards were rebuilt yesterday and they look healthy. The other nine are queued. The rebuild passes on every shard we have tried, so the remaining nine should be fine. Query rewriting is the piece that is not done. The rewriter still normalizes diacritics before stemming, which is backwards for the Turkish locale, and it will produce wrong results for a small number of queries. It is a narrow case and probably not worth blocking the rollout on. ## What I think is going on with the slow tail `[assumed]` — the slow queries that remain are almost certainly the ones hitting the multi-field disjunction path. That code has not changed, but it is the only thing left that could explain the shape of the tail. Worth a look early. ## Notes for whoever picks this up Do the backfill first — it is the long pole and everything else can happen while it runs. Start it before you do anything else, because it takes most of a day and you do not want to be waiting on it later. The staging cluster credentials rotated last week, so grab fresh ones before you start. Currently the runbook still has the old ones in it. ## What this needs - The service repository, on the `reindex` branch. - Access to the staging cluster. - A decision from the platform team on whether the Turkish locale blocks the rollout. - The load-test dashboard, for the latency numbers.
Session handoff example: the note afterThe same note with every claim labelled, and the decisions nobody has made listed as decisions.example file
# Handoff — the search reindex EXAMPLE FIXTURE — the repaired "after" half of the session-handoff worked example. It is a demonstration input, not a real handoff. Written 2026-09-09, closing the session that landed the new analyzer. Every claim below is labelled. A **measured** claim names the command that produced it. An **assumed** claim names what would show it to be wrong. ## What landed `[measured]` — the new analyzer is on `main` at `a91c4e2` and the staging reindex exits 0: ``` $ ./bin/reindex --cluster staging --verify 12 shards planned, 3 rebuilt, 9 queued analyzer icu_v2 checksum ok exit 0 ``` `[measured]` — p99 query latency on staging fell from 840 ms to 505 ms over the 2026-09-08 load-test window: ``` $ ./bin/loadtest --window 2026-09-08 --percentile 99 --compare icu_v1 icu_v1 p99 840 ms icu_v2 p99 505 ms (-39.9%) ``` That is a staging number against synthetic traffic. It is not a production number and has not been compared against one. ## What is open `[measured]` — 3 of the 12 shards are rebuilt; the other 9 are queued, per the `--verify` output above. Nothing has been rebuilt in production. `[assumed]` — the 9 queued shards will rebuild the same way the first 3 did. Nothing distinguishes them in the shard map, but no shard over 40 GB has been rebuilt and four of the nine are larger than that. **Test it** by rebuilding the largest queued shard alone, before the batch: if it needs more than the 90-minute window, the batch plan is wrong. `[measured]` — the query rewriter normalizes diacritics before stemming, which is wrong for the Turkish locale. `./bin/rewrite --locale tr --explain "İSTANBUL"` returns the `istanbul` stem instead of `i̇stanbul`. Ticket 4471 has the trace. ## What the next session must not assume - **That the rollout is unblocked.** The Turkish locale defect is real and measured; whether it blocks is a ruling, not a finding, and nobody has made it. Do not decide it in passing. - **That the latency win holds in production.** See the staging caveat above. - **That the runbook credentials work.** They were rotated 2026-09-02 and the runbook copy was not updated. ## Fence Read and write only `services/search/` and `ops/reindex/`. **Do not open `services/ranking/`.** The disjunction path lives there, it is mid-migration under another team, and a change landing in it stops this thread and asks. A failing test in that directory is not a work item for this session. ## Resources - `[tree]` the service repository, on `main` at `a91c4e2`. - `[creds]` staging cluster credentials, rotated 2026-09-02 — the runbook copy is stale and must not be used. - `[ruling]` the platform team, on whether the Turkish locale blocks rollout. Nothing downstream of that question can be opened without it. - `[dashboard]` the load-test dashboard, for the latency comparison.
Both notes are a demonstration file about a software project, not notes from a real one. The Session Discipline page shows the same pattern on an operations example.