@datarails-ai/dr-cli 0.0.1-locked → 1.6.71

package/dist/skills/dr-error-enrichment/reference/safety-backup.md

@@ -0,0 +1,122 @@
+# Safety and backup — invariants, write gating, import policy
+
+Read [the `dr-cli` skill's reference/safety.md](../../dr-cli/reference/safety.md)
+for the underlying confirm-token and prod-gate mechanics. That file lives in the
+`dr-cli` skill, not this one — this skill's safety file is the one you are
+reading.
+
+## Three invariants for every server-modifying run
+
+**1. Confirm the target server explicitly.** Ask (AskUserQuestion) which server
+to change — never infer it from earlier context in the conversation. Prod keys
+are `US`, `US2`, `UK`, `CA`, `EU`, `DEMO` (DEMO is customer-facing prod, not a
+sandbox). Demonstrate on `DEV` / `TEST-*` first when the user is undecided.
+
+**2. Back up every reachable server first.** Before the first write of a
+session, one command — `export` takes the same sweep flags as `list` / `stats`,
+and `--out` is a **directory** when sweeping, one `<SERVER>.csv` per server:
+
+```bash
+dr error-enrichments export --all-servers --out ~/dr-enrichment-backups/$(date -u +%Y-%m-%dT%H%M%SZ)
+```
+
+Back up **all** servers, not just the target: a reconcile session usually
+touches more than one, and the diff baseline is worth as much as the restore.
+Use `--servers A,B` to narrow it deliberately, and `--include-test` to pull
+`DEV` / `TEST-*` in as well. `--out` is **required** when sweeping and must name
+a directory — concatenating N servers into one CSV produces N header rows that
+`import` cannot read back, which is the one thing a backup has to survive.
+
+**Report which servers actually backed up, before the first write.** The sweep
+writes the files it could and keeps going, printing one stdout line per server —
+`Wrote N rules to <dir>/<SERVER>.csv` for the ones that worked, and a
+`<SERVER> — skipped: …` / `<SERVER> — error: …` line for the ones that did not.
+A server with no stored keychain identity is **skipped** and does **not** make
+the command fail; only a real export failure does. So exit 0 is *not*
+"everything is backed up" — read the per-server lines and tell the user by name
+which servers have a CSV and which do not. A server you are about to write to
+with no backup of its own has no revert path and no diff baseline: fix the login,
+or get an explicit decision to proceed without one, before writing to it.
+
+A single server still works the way it always did — `export --server <S> --out
+<file>.csv`, where `--out` is a plain file. Use that only when you have
+deliberately narrowed the scope to one server. Do **not** rebuild the sweep as a
+shell loop: a loop that ends each iteration in `|| echo "skip $S"` turns a failed
+export into one quiet line, and a server with no backup then reads exactly like
+a server with one.
+
+**3. Know the revert path before you need it — and prefer the surgical one.**
+The CSV backup carries `id`, so a revert is a per-rule replay:
+
+- rule changed → `update <id>` back to the backed-up field values
+- rule you created → `delete <id>`
+- rule you deleted → `create` from the backed-up row (it returns a **new id**)
+
+Batch forms make this cheap: one `update --payload-file` with an array of
+`{id, ...original fields}` undoes a whole batch in a single confirmed run.
+Do **not** reach for `import` to undo anything — see the import policy below.
+
+## Write gating
+
+Every mutation is two-step: run it without `--confirm-token`, relay the printed
+plan to the user, then re-run with the token. Tiers (`src/commands/_prodGateTiers.ts`):
+
+- **`create` / `update` — Tier B.** Token only, on every server. Batch forms are
+  tiered separately (`error-enrichment-batch|create`, `error-enrichment-batch|update`)
+  and are **also Tier B**: a single token covers the whole set.
+- **`delete` / `import` — Tier A.** On a prod server the binary additionally
+  demands a challenge word typed by a human in a desktop dialog or TTY; it
+  refuses non-zero in a headless shell. Don't invent a chat-side word ritual —
+  get the user's "yes", re-run with the token, and let the binary prompt them.
+  A batch `delete` (`error-enrichment-batch|delete`) is Tier A too, and **one**
+  gate covers the whole set — which is exactly why the plan's per-rule lines have
+  to be read rule by rule rather than counted.
+
+A batch write binds its token to the targets *and* the field values, so an edited
+payload file invalidates it; a single-target write binds the target only, so an
+edited field flag does **not**. The full rule is in
+[core.md](core.md) under *Confirm-token binding* — read it before you reuse any
+token.
+
+## Import policy
+
+**Default to `update` / `create` for every fleet change.** Batch `update` (shared
+patch or per-rule array) and batch `create` cover reconcile, approval sweeps, and
+message rewrites — that is what they exist for. `import` is not part of the
+normal loop and must not be selected on your own initiative, however convenient
+the CSV looks.
+
+Use `import` **only when the user explicitly asks for it by name** (a genuine
+restore-from-catastrophe). Even then, before running it, state plainly that
+`import` is wipe-and-replace — the server deletes **every** rule on that server
+and bulk-creates from the CSV — and that it therefore:
+
+- **resets `hits`, `thumbs_up`, and `thumbs_down` to 0.** The import path ignores
+  those columns. That is the feedback history the whole maintenance flow runs on:
+  no hits means no `needs_attention` list, no `top_hits`, no thumbs-down ranking,
+  and the loss is permanent — nothing recomputes it.
+- **assigns brand-new ids.** The `id` column in the CSV is not honoured, so every
+  rule id on that server changes and any id quoted earlier in the conversation,
+  in a ticket, or in another server's mapping goes stale.
+- **drops server-only rules** that are not in the CSV.
+
+Then get an explicit confirmation of *that* — the analytics loss specifically —
+before running it. If the user's actual goal was "make server B look like server
+A", say so and offer the per-rule route instead.
+
+## Batch-write etiquette
+
+- **Relay the whole plan.** It names every affected rule — a batch `delete` prints
+  one compact line per rule, counters included — and a summarised "12 rules" hides
+  the one wrong id. Paste the list.
+- **One server per run.** Keep a fleet change as N separate confirmed runs so each
+  server's plan is reviewed against that server's current state.
+- **Re-read the summary table after execution.** The run continues past failures
+  and exits non-zero, so the summary — not the exit code, not the plan — is the
+  record of what landed and which new ids `create` returned. Retry only the failed
+  ids.
+- **Verify after writing** with `dr error-enrichments get <ids...> --server <S>`,
+  which takes the same id list you just wrote. With `--json`, remember the shape
+  flips: a bare object for one id, an array for two or more, and an id that failed
+  to read is missing from the array rather than represented in it — check the exit
+  code and the stderr warnings, not just the payload ([core.md](core.md)).

package/dist/skills/dr-error-enrichment-author/SKILL.md

@@ -0,0 +1,219 @@
+---
+name: dr-error-enrichment-author
+description: Author, edit, or delete integration error-enrichment rules — the regex-to-readable-message rules Datarails shows a user when a sync fails. Drafts and server-validates the pattern, gets the customer-facing wording signed off, picks a rank, writes it through the confirm gate, and offers propagation to the other servers. Reviewing and approving existing drafts belongs to dr-error-enrichment-maintain, not here. Use when a specific error needs a rule, or an existing rule needs fixing or removing. Triggers - "add an error enrichment rule", "make this error message readable", "fix the wording of this error", "this error shows no explanation", "why does this integration error show no explanation", "delete an enrichment rule", "test this error regex", "the regex isn't matching".
+---
+
+# dr-error-enrichment-author — author, edit, or delete a rule
+
+## Read first
+
+This flow assumes both shared references and does not repeat them:
+
+- [../dr-error-enrichment/reference/core.md](../dr-error-enrichment/reference/core.md)
+  — what a rule is, permissions, the full `dr error-enrichments` command surface,
+  how matching actually works (`re.match` anchoring, rank order, drafts stealing
+  the hit), where to get raw error text off a tenant.
+- [../dr-error-enrichment/reference/safety-backup.md](../dr-error-enrichment/reference/safety-backup.md)
+  — confirming the target server, backing up before the first write, the revert
+  path, the Tier A/B write gates, and why `import` is never an edit tool.
+
+Confirm the target server and take the backup **before** step 8 below, not after:
+`dr error-enrichments export --server <S> --out /tmp/ee-<S>.csv` for the one
+server you are writing to, or
+`dr error-enrichments export --all-servers --out /tmp/ee-backup/` (with a sweep
+`--out` is a directory, one `<SERVER>.csv` per server) when the session is likely
+to spread to the fleet.
+
+## Authoring flow
+
+1. **Get real samples.** Ask for the raw error text. If the user only names a
+   symptom, pull samples from the tenant (`integrations get`,
+   `integrations query-status --json`) or mine groundcover — the query mechanics
+   and the env-to-server mapping are in
+   [../dr-error-enrichment/reference/groundcover.md](../dr-error-enrichment/reference/groundcover.md),
+   and `dr-error-enrichment-improve` is the flow built on it. A rule written from
+   a paraphrase matches nothing.
+
+2. **Check for an existing rule first.** A near-miss rule is usually better
+   edited than duplicated:
+
+   ```bash
+   dr error-enrichments list --server <S> --integration-type <T> --json
+   ```
+
+   Read what the vendor already covers, so the rank you pick next doesn't
+   shadow a good rule.
+
+3. **Draft the pattern** with a leading `.*` and escaped metacharacters, keeping
+   the volatile parts (ids, paths, hostnames, quantities) as `.*` or character
+   classes so it generalises past this one sample.
+
+4. **Validate it server-side** against the real samples plus at least one error
+   that must *not* match:
+
+   ```bash
+   dr error-enrichments test-regex --server <S> --pattern '.*INVALID_LOGIN.*' \
+     --sample 'Error: INVALID_LOGIN for user x' --sample 'Unrelated timeout'
+   ```
+
+   Iterate until matches and non-matches are both right. `valid: false` means
+   the regex itself doesn't compile. `test-regex` runs the same `re.match` plus
+   newline-stripping the resolver does — trust it over local regex reasoning,
+   and never hand-verify a pattern you could test.
+
+5. **Draft the message and steps.** `description` states what went wrong in the
+   customer's language — no stack traces, no internal identifiers, no vendor
+   error code as the whole message. `resolution_steps` are ordered, concrete
+   actions the customer or CSM can actually take. Propose both to the user and
+   let them approve the wording; this text ships to customers.
+
+6. **Pick a rank.** Rank is priority within the vendor: specific rules above
+   general catch-alls, or the general one matches first and hides the better
+   message. The server shifts the sibling rows to make room — pass the rank you
+   want and never renumber siblings by hand.
+
+7. **Set `classification`** (`DataSource` | `Filebox` | `Unclassified`) and
+   decide `approved`. Create as a draft (`--approved false`) only when the
+   pattern still needs field validation, and say out loud what that costs: a
+   draft steals the hit from any lower-ranked approved rule and shows the user
+   nothing, so a draft left in place is an active user-facing gap, not a
+   harmless staging state.
+
+8. **Write it** through the two-step confirm (run without `--confirm-token`,
+   relay the plan, re-run with the token), then verify:
+
+   ```bash
+   dr error-enrichments get <id> --server <S>
+   ```
+
+9. **Propagate.** A rule worth adding on one server is almost always worth
+   adding on the others. Offer `dr-error-enrichment-reconcile` rather than
+   leaving the fleet inconsistent.
+
+## Several rules in one pass
+
+The CRUD subcommands take batches. Same gating, same plan-then-token cycle —
+one confirm covers the batch.
+
+**Create many.** `--payload-file` accepts either one rule object (as before) or
+an **array** of rule objects:
+
+```bash
+cat > /tmp/new-rules.json <<'JSON'
+[
+  {"integration_type": "NetSuite", "rank": 3, "re_pattern": ".*INVALID_LOGIN.*",
+   "description": "...", "resolution_steps": ["...", "..."], "approved": true},
+  {"integration_type": "NetSuite", "rank": 4, "re_pattern": ".*SSS_INVALID_SCRIPT.*",
+   "description": "...", "resolution_steps": ["..."], "approved": false}
+]
+JSON
+dr error-enrichments create --payload-file /tmp/new-rules.json --server <S>
+```
+
+**One patch across several rules** — positional ids, field flags applied to
+every id:
+
+```bash
+dr error-enrichments update 12 19 24 --approved true --server <S>
+```
+
+That `--approved true` form is **the last step of the approval protocol, not a
+shortcut past it**. `dr-error-enrichment-maintain` owns approval: it pulls each
+draft, shows it to the user against approved siblings for the same vendor, tests
+the pattern against a real sample, and takes a per-rule confirmation. Only drafts
+that have each been through that cycle may be flipped together here. If the
+request that reached you is "approve rules 12, 19 and 24", the answer is to run
+the maintain protocol first — never to run this line.
+
+`--rank` is rejected with several ids: rank is a per-rule priority within a
+vendor and the server shifts siblings on every change, so one shared rank across
+several rules is never what you meant. Change ranks one rule at a time, or give
+each rule its own rank in an array payload.
+
+**A different patch per rule** — an **array** of `{id, ...fields}` entries and
+no positional ids:
+
+```bash
+cat > /tmp/patches.json <<'JSON'
+[
+  {"id": 12, "rank": 2},
+  {"id": 19, "description": "...", "resolution_steps": ["..."]}
+]
+JSON
+dr error-enrichments update --payload-file /tmp/patches.json --server <S>
+```
+
+**Several deletions under one gate:**
+
+```bash
+dr error-enrichments delete 31 32 33 --server <S>
+```
+
+The delete plan prints one compact line per rule — id, integration type, rank,
+pattern, and the hits/thumbs counters — so relay the plan verbatim: that block is
+the user's only view of what is about to be destroyed.
+
+Verify a batch afterwards with the same id list:
+
+```bash
+dr error-enrichments get 12 19 24 --json --server <S>
+```
+
+`get --json` returns a bare object for one id and an **array** for two or more,
+so parse accordingly.
+
+Four things to hold onto with batches:
+
+- **A failure does not stop the run.** Each item is sent in turn, per-item
+  failures are recorded, and the command prints a summary table naming what
+  succeeded (with the new id for each created rule) and what failed, then exits
+  non-zero. The table — not the exit code — is what tells you which items
+  actually landed; retry only those.
+- **The confirm token binds the field values too.** A batch plan hashes the
+  targets *and* the values being written, so editing the payload file or changing
+  a field flag between plan and confirm invalidates the token — re-run the plan
+  step and relay the new plan. (A single-target write binds only its target, as
+  it always has, so the same care applies there by hand.)
+- **Array entries are validated before anything is sent.** A wrong field type or
+  a repeated id is rejected up front, and the message names the offending entry
+  by its position in the file (`entry 3: …`) — fix that entry and re-plan rather
+  than retrying with the old token.
+- **A bulk create into one `integration_type` shifts that vendor's ranks.** Each
+  insert makes room for itself, so ranks you assumed while drafting may not be
+  the ranks you end up with. Re-run
+  `dr error-enrichments list --server <S> --integration-type <T> --json`
+  afterwards and check the order is what you intended.
+
+Batch writes are still one server per run — there is no cross-server write.
+
+## Deleting a rule
+
+Show the user the rule's `hits`, `thumbs_up`, and `thumbs_down` from the plan
+step before confirming. A rule with meaningful hits is usually better re-pointed
+with `update` (new pattern, better wording) than deleted, because deleting it
+drops its feedback history with it — and that history is what
+`dr-error-enrichment-maintain` ranks its work from. Delete is Tier A: on a prod
+server the binary itself prompts a human for a challenge word, so get the user's
+"yes", re-run with the token, and let the binary do the asking.
+
+## Pitfalls
+
+| Mistake | Fix |
+|---|---|
+| Pattern without a leading `.*` | `re.match` anchors at the start — write `.*NEEDLE.*` |
+| Writing a pattern expecting `\n` | Newlines are stripped before matching; the error is one long line |
+| Hand-verifying a regex you could test | `test-regex` runs the server's own matcher — use it, with a non-matching sample too |
+| Pattern fitted to one sample | Generalise ids, paths, hostnames, quantities to `.*` or a character class |
+| Adding a rule that duplicates a near-miss | `list --integration-type <T>` first; edit the existing rule instead |
+| A general rule ranked above a specific one | The general one matches first and hides the better message — rank specific first |
+| Renumbering siblings by hand after a rank change | The server shifts them; pass the rank you want and leave the rest alone |
+| Leaving a draft in place "for now" | It steals the hit and shows nothing — approve it, fix it, or lower its rank |
+| Vendor codes or stack traces in `description` | Customer-facing text — plain language, wording approved by the user |
+| Expecting `--resolution-step` with no value to clear the steps | PATCH-omit semantics — clear with `--payload-file` and `{"resolution_steps": []}` |
+| Reading only the exit code of a batch | It is non-zero if *any* item failed — read the summary table for what landed |
+| Flipping `--approved true` over a list of drafts here | Approval is `dr-error-enrichment-maintain`'s protocol — one rule at a time, then batch the confirmed set |
+| Re-using a batch token after editing the payload file | The batch token binds the values too; edit means re-plan |
+| `--rank` with several positional ids | Rejected — ranks are per rule; use one id at a time or an array payload |
+| Assuming drafted ranks survive a bulk create | Each insert shifts siblings; re-`list` the vendor afterwards |
+| Deleting a rule with real hits | Re-point it with `update`; deleting discards the feedback history |
+| Writing on one server and stopping | Offer `dr-error-enrichment-reconcile` — per-server drift is the problem this tooling exists to fix |

package/dist/skills/dr-error-enrichment-improve/SKILL.md

@@ -0,0 +1,218 @@
+---
+name: dr-error-enrichment-improve
+description: Continuous improvement for integration error enrichment - mine groundcover for sync errors that no rule matches yet, rank them by volume, triage out the ones caused by our own bugs, and turn the rest into proposed rules. Use when the user wants to know what the rule table is missing rather than to edit a rule they already have in mind. Triggers - "which errors have no rule", "find unmatched integration errors", "suggest new enrichment rules", "what should we add to the error enrichment rules", "mine groundcover for integration errors", "what are we not explaining to customers", "is this error a bug or a missing rule".
+---
+
+# dr-error-enrichment-improve — find the errors nothing matches
+
+This is the outward-looking pass of the error-enrichment family: every other flow
+starts from a rule that exists, this one starts from the errors that have none.
+You are not fixing a rule the user named — you are finding the errors that reach
+customers with **no explanation at all**, ranking them by how much traffic they
+represent, sorting out which of them are our own bugs, and proposing rules for
+what is left.
+
+That sort is not a formality. A rule is a message to a customer about something
+they can act on; written over a defect of ours it tells them to fix what they
+cannot, and it makes the defect stop looking like one. **Some candidates should
+become bugs, not rules** — and a run that ends in three bug reports and no rules
+did its job.
+
+Authoring the chosen rules is `dr-error-enrichment-author`. Approving drafts and
+fixing disliked rules is `dr-error-enrichment-maintain`.
+
+## Read first
+
+- [../dr-error-enrichment/reference/groundcover.md](../dr-error-enrichment/reference/groundcover.md)
+  — the gcQL query mechanics, the env-to-server mapping, and the hash-not-text
+  caveat. This flow is mostly that file; do not compose queries from memory.
+- [../dr-error-enrichment/reference/core.md](../dr-error-enrichment/reference/core.md)
+  — matching semantics. A proposal that ignores `re.match` anchoring is dead on
+  arrival, and a proposed rank that sits under an existing catch-all never fires.
+- [../dr-error-enrichment/reference/jira-bugs.md](../dr-error-enrichment/reference/jira-bugs.md)
+  — the bug sweep in step 6: the `System area` field and its exact option value,
+  the JQL that actually returns rows, how to tell our defect from the customer's
+  condition, and how to file the bug if one is missing.
+- [../dr-error-enrichment/reference/safety-backup.md](../dr-error-enrichment/reference/safety-backup.md)
+  — before any of the proposals become writes. The backup is one command:
+  `dr error-enrichments export --all-servers --out /tmp/ee-backup/` (with a
+  sweep, `--out` is a directory and each server lands as its own
+  `<SERVER>.csv`).
+
+## The loop
+
+**1. Pick the region and the window, and prove they line up.** Ask which server
+the user intends to improve, then map it to the groundcover env before querying —
+`UK` is `prod-uk*`, `CA` is `prod-canada-central`, `DEMO` is `prod-demo`, and
+`US`/`US2` are ambiguous across the three US envs and `EU` is not mapped at
+all, so resolve those explicitly (see the reference). Mining one region's logs to justify a rule you then write to
+another is the failure mode this step exists to prevent. Start with a tight
+window and widen only after it returns rows.
+
+**2. Find the unmatched-resolve marker lines.** The monolith logs every resolve
+that matched nothing with `[ErrorEnrichment] No matching rule`. Query on the bare
+keyword — a leading wildcard can't use the full-text index and times out on a
+busy env:
+
+```
+ErrorEnrichment | stats count()
+ErrorEnrichment | fields _time, content | limit 20
+```
+
+**3. Group by vendor to find the worst connector.** The marker's fields are
+printf-formatted inside the message text, not indexed attributes, so extract them
+first or you get one silent empty group:
+
+```
+ErrorEnrichment | extract_regexp "vendor_name=(?P<vendor>[^ ]+)" from content
+  | stats by (vendor) count() as unmatched | sort by (unmatched desc) | limit 20
+```
+
+**4. Group by error hash to rank distinct offenders.** Identical
+`err_sha256_prefix` values are the same normalised error, so this counts *distinct*
+unmatched errors rather than volume of one noisy tenant. The top rows are the
+highest-value *candidates* — a lot of traffic each, still to be cleared by
+step 6:
+
+```
+ErrorEnrichment | extract_regexp "err_sha256_prefix=(?P<sig>[0-9a-f]+)" from content
+  | stats by (sig) count() as hits | sort by (hits desc) | limit 50
+```
+
+**5. Recover the raw text for each candidate.** The marker carries only a hash and
+a length **by design** — vendor errors can embed customer paths and tokens, so the
+text is deliberately kept out of the log. Get it from the tenant instead
+(`integrations get <id>`, or `integrations query-status --json` for the `query_id`
+the marker names) or from the vendor sync error logs around the same timestamp and
+`datasource_id`. Without real text you cannot write a pattern, only guess at one.
+
+**6. Triage each candidate against the integration bugs before it becomes a
+proposal.** Read
+[jira-bugs.md](../dr-error-enrichment/reference/jira-bugs.md) for the exact
+queries; the shape of the step is:
+
+- Sweep the open integration bugs **and** the ones fixed in the last ~60 days —
+  `cf[10717] = "Integration"` in project `DR` (the option is singular
+  `Integration`; a wrong value returns zero rows and no error). A signature whose
+  volume stops the week a fix shipped needs nothing at all.
+- The `System area` field is optional on the create screen and often empty, so
+  follow with a free-text `text ~ "<stable phrase>"` pass with no area filter
+  before calling a signature unticketed.
+- Then classify each candidate: **customer- or vendor-side** → propose a rule;
+  **our defect with a ticket** → no rule, report the signature against the bug
+  key, because your volume figure is priority evidence that bug does not have
+  yet; **our defect with no ticket** → no rule, flag it and offer to open one;
+  **unclear** → no rule, say what would settle it.
+- Classify on **whose code raised it**, not on what the error looks like.
+  Tracebacks, `NoneType`, un-enriched exception bodies, 5xx and timeouts all
+  reach us from vendors and from the customer's own machine too — they are clues
+  that raise the question. Settle it with the log source, the host, and whose
+  endpoint answered; if those don't converge the verdict is **unclear**, which is
+  still not a rule.
+- Opening the bug is outward-facing: show the summary and body first and wait for
+  a yes, group related signatures into one ticket, and set `customfield_10717`
+  (`{"id": "20748"}`) or the next sweep cannot see it.
+- **Redact the error text in the draft you show, before anything is filed** —
+  credentials and connection strings, usernames, hosts/DSNs/paths, customer and
+  account identifiers, and any row-level financial values. Keep the exception
+  class, message template, module, vendor error code and the
+  `err_sha256_prefix`; that is what the fix needs. The checklist is in
+  [jira-bugs.md](../dr-error-enrichment/reference/jira-bugs.md) — nothing
+  sanitises this for you.
+
+If the Atlassian tools are not available in the session, **say so and mark the
+proposals un-triaged** — a skipped sweep produces a list that looks exactly like
+a triaged one.
+
+**7. Sanity-check that nothing already covers it.** A "missing" rule is often an
+existing rule that is too narrow, or one that is a draft and therefore invisible:
+
+```bash
+dr error-enrichments list --server <S> --integration-type <T> --json
+```
+
+Check the vendor's existing ranks at the same time — a proposal has to sit above
+whatever catch-all would otherwise swallow it.
+
+**8. Draft one proposal per surviving candidate.** Each proposal states: the
+vendor (`integration_type`), the proposed pattern, the proposed `description` and
+`resolution_steps` in customer language, the samples it was built from, and the
+estimated volume it would cover (the `hits` count from step 4). Volume is what
+makes the list rankable — without it the user is choosing blind.
+
+## Handing the results off
+
+A run has **two** outputs, and the second one is not a footnote. Report them as
+separate lists:
+
+1. **Ranked rule proposals** — the candidates that are genuinely the customer's
+   or the vendor's to fix.
+2. **Defects** — the candidates held back in step 6, each with its volume and
+   either the bug key it belongs to or an offer to file one. Say plainly that
+   these deliberately get no rule and why.
+
+Present the proposals and let the user choose which to write. Do not write the
+whole list because it is on the list.
+
+- Route the chosen ones to `dr-error-enrichment-author` for the per-rule
+  treatment, **or** write them together as a batch:
+  `dr error-enrichments create --payload-file proposals.json --server <S>` with an
+  array of rule objects. Batch writes are sequential and a per-item failure does
+  not stop the run — read the summary table afterwards to see which ids landed.
+  Every entry is type-validated before anything is sent, and the error names the
+  offending entry by its position in the file (`entry 3: …`), so fix that entry
+  and re-plan. Re-planning is
+  required anyway: the batch confirm token binds the field values as well as the
+  targets, so a payload edited after the plan was relayed will not redeem.
+- **Validate every pattern with `test-regex` before it goes into the payload
+  file**, against the real samples *and* at least one error that must not match.
+  A batch create does not validate patterns for you.
+- Create as drafts (`approved: false`) when a pattern still needs field
+  validation. Say out loud what that costs: a draft steals the hit and shows the
+  user nothing, so it is strictly worse than no rule until it is approved. A draft
+  is a commitment to come back — book the follow-up through
+  `dr-error-enrichment-maintain`.
+
+## Prove the pipeline before reporting zero
+
+An empty gcQL result is indistinguishable from a wrong env, a too-narrow window,
+or a misspelled field — none of those error, they all return nothing. Run a query
+you *expect* to return rows (`ErrorEnrichment | stats count()`) and confirm the
+env resolves before telling the user there are no unmatched errors. "We're fully
+covered" is a much more expensive thing to say wrongly than "I couldn't reach the
+logs".
+
+The bug sweep fails the same silent way: a wrong `System area` option value
+returns zero rows without erroring, so "no known bug" and "bad JQL" look
+identical. Prove that query returns rows too before you let a candidate through
+as nobody's fault but the customer's.
+
+## Customer data
+
+Raw vendor error text is customer data. Use it to build the rule; keep it out of
+chat summaries beyond what the rule actually needs; put sanitised text in
+`examples`. The hash-only marker exists for this reason — don't undo it by pasting
+whole error bodies into the conversation, or into a Jira ticket, which is a wider
+audience still.
+
+## Pitfalls
+
+| Mistake | Fix |
+|---|---|
+| `stats by (vendor_name)` on the marker line | Those are text inside `content`, not fields — `extract_regexp` first, or you get one empty group |
+| `content:*ErrorEnrichment*` | Leading wildcard can't use the index; query the bare keyword `ErrorEnrichment` |
+| Treating an empty result as "no unmatched errors" | Verify env, window, and field names with a query you expect to return rows |
+| Mining `prod-uk` and writing the rule to `US` | Resolve the env-to-server mapping first; volume evidence is per region |
+| Expecting raw error text from the marker | It is hash + length only; pull the text from the tenant or the vendor sync logs |
+| Ranking candidates by raw line count | Group by `err_sha256_prefix` — one noisy tenant is not the same as a widespread error |
+| Proposing a rule for an error our own code raised | Triage against the integration bugs first — a rule over a defect blames the customer and buries the bug |
+| Skipping the bug sweep because the errors "look like vendor errors" | Tracebacks and 5xx from our services hide in vendor-shaped noise; the sweep is two queries |
+| Sweeping only *open* bugs | A fix shipped last week disqualifies the rule too — include `resolved >= -60d` |
+| Trusting `cf[10717]` alone, or writing `"Integrations"` | The field is optional and often empty, and the option is singular `Integration` — add a `text ~` pass, and remember a bad option value returns zero rows without erroring |
+| Filing a bug per signature, or filing one unasked | Group related signatures, show the ticket first, and set `System area` so the next sweep sees it |
+| Presenting proposals when the Jira sweep could not run | Say they are un-triaged — the list looks the same either way |
+| Proposing a pattern with no leading `.*` | `re.match` anchors at the start; it will match nothing in production |
+| Writing the whole proposal list unasked | Present ranked, let the user pick — each rule is user-facing text |
+| Batch-creating patterns straight from the proposal | `test-regex` every one first; `create` does not validate matching behaviour |
+| Editing `proposals.json` after relaying the plan | The batch token binds the values too — re-run the plan step and relay it again |
+| Leaving new drafts behind | A draft steals the hit and shows nothing — hand it to `dr-error-enrichment-maintain` |