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

package/dist/skills/dr-error-enrichment/reference/core.md

@@ -0,0 +1,257 @@
+# Core — what enrichment rules are, the command surface, how matching works
+
+## What a rule is
+
+When an integration sync fails, Datarails matches the raw vendor error against a
+table of **enrichment rules**. A rule maps a regex to a readable `description`
+plus `resolution_steps`, and collects thumbs up/down feedback.
+
+Rules live **per server** in each region's own database — there is no global
+table and no cross-server sync, so the same rule can exist on `US` and be
+missing (or wrong) on `UK`. Rule `id`s are per-server database ids: the same
+logical rule has a different id on every server.
+
+## Permissions
+
+The admin API is restricted to **Datarails admins** and members of the
+**`Integrations Team`** permission group on the parent org. A `403`/`405` on any
+subcommand means the logged-in identity lacks that — confirm with
+`dr whoami --server <S>` and escalate rather than switching to another
+identity's credentials.
+
+## Command surface
+
+```
+dr error-enrichments list       [--server S | --all-servers | --servers A,B] [--include-test]
+                                [--integration-type T]... [--classification C]... [--approved true|false]
+                                [--search Q] [--json]
+dr error-enrichments stats      (same server + filter flags) [--json]
+dr error-enrichments get        <ids...> --server S [--json] [--timeout SECS]
+dr error-enrichments create     --server S --integration-type T --rank N --pattern RE --description D
+                                [--resolution-step S]... [--example E]... [--classification C] [--approved true|false]
+dr error-enrichments create     --server S --payload-file f.json      # one object OR an array of rule objects
+dr error-enrichments update     [ids...] --server S (same field flags) # PATCH, same patch applied to every id
+dr error-enrichments update     --server S --payload-file patches.json # array of {id, ...fields}, no positional ids
+dr error-enrichments delete     <ids...> --server S
+dr error-enrichments test-regex --server S --pattern RE (--sample S... | --samples-file f)
+dr error-enrichments export     [--server S | --all-servers | --servers A,B] [--include-test]
+                                [--out PATH]                          # PATH is a DIRECTORY when sweeping
+dr error-enrichments import     --server S --file backup.csv          # DESTRUCTIVE — see safety-backup.md
+```
+
+An array `--payload-file` on `create` / `update` takes neither positional ids nor
+field flags — array mode carries every field inside each entry, and the command
+rejects the combination rather than guessing which one wins.
+`create` / `update` / `delete` also take `--timeout <seconds>` for the
+whole-command budget (see *Execution semantics*).
+
+Exact flags come from `dr error-enrichments <sub> --help` — the binary is
+authoritative. Reads accept `--all-servers` / `--servers`; **writes never do**
+(one `--server` per mutation, by design). `export` is a read, so it sweeps too —
+that is the whole backup invariant in one command, see
+[safety-backup.md](safety-backup.md).
+
+### Bulk forms
+
+`get`, `update`, and `delete` take a variadic id list; `create` takes an array
+payload. Two ways to update many rules:
+
+- **Shared patch** — `update 7 12 30 --approved true --server <S>` applies the
+  *same* field changes to every id. Use it for a uniform flip (approving a batch,
+  re-classifying a vendor's rules).
+- **Per-rule patches** — `update --payload-file patches.json --server <S>` where
+  the file is an array of objects each carrying its own `id` plus the fields to
+  change. Use it for a reconcile run where every rule gets different text. Do not
+  pass positional ids in this mode.
+
+```json
+[
+  {"id": 7,  "approved": true},
+  {"id": 12, "description": "NetSuite rejected the login.", "rank": 3}
+]
+```
+
+`create --payload-file` accepts one object (as before) or an array of rule
+objects for a batch create.
+
+Array entries are type-checked before anything is sent, and the message names the
+offending position (`entry 3: expected a JSON object, got a string`). Fix the
+entry the message names — the index is 1-based and matches file order.
+
+**`get --json` changes shape with the id count.** One id returns a **bare
+object**; two or more return an **array**. `get 7 --json | jq '.approved'` works,
+`get 7 12 --json | jq '.approved'` returns `null` — use `jq '.[].approved'` (or
+`.[] | select(.id == 7)`) for a batch. The array holds only the rules that were
+readable: a failed id is **not** represented in the JSON at all, and if no id was
+readable stdout stays **empty** rather than printing `[]`. Failures come back as
+`warning: rule <id>: …` lines on **stderr** plus a non-zero exit. So when you
+parse a batch `get`, check the exit code and compare the returned ids against the
+ids you asked for — never infer "the rule is gone" from a short array, and never
+read empty stdout as "no such rules".
+
+**"Batch" means two different things in this file, and they draw the line in
+different places.** For *execution semantics* (below) a batch starts at **two
+targets**: a run with one target — one positional id, a single-object
+`--payload-file`, **or a one-entry array `--payload-file`** — behaves exactly
+like the pre-batch single-rule command. It prints the one-line success message
+(`Updated error-enrichment rule 7.`), not a summary table, and a failure
+propagates as the server's own error rather than a one-row `FAILED` table. So
+never tell a user (or yourself) to "read the summary table afterwards" without
+checking the target count first: on a one-entry `proposals.json` there is no
+table, and the bare error *is* the report. For *confirm-token binding* (further
+below) the line is elsewhere: an array `--payload-file` of **any** length,
+including one entry, binds as a batch.
+
+**Execution semantics (two or more targets).** Batch requests are sent sequentially, and the run gets a
+timeout scaled to the number of targets (the flat single-call budget plus a
+per-target allowance, capped) instead of the single-call default, so a long batch
+does not abort just for being long; `--timeout <seconds>` on
+`get`/`create`/`update`/`delete` overrides it, and one target keeps exactly the
+budget it had before batches existed. A per-item failure is recorded and the run
+**continues**; afterwards a summary table names what succeeded (with the new ids
+for `create`) and what failed, and the command exits non-zero. So a partial batch
+is normal and visible — read the summary before retrying, and retry only the ids
+that failed.
+
+If the run *times out*, the summary marks the untouched targets
+`not attempted — run timed out` and the thrown error says so explicitly. Treat it
+as neither "done" nor "nothing happened": a request already in flight may have
+landed. Re-read the affected rules with `get` before re-running, and raise
+`--timeout` rather than re-issuing the same batch blind.
+
+**Confirm-token binding — read this before reusing a token.** What the token
+binds depends on how many targets the run has, and the two halves behave
+differently:
+
+- **Single target** — one positional id with flag-built fields, or a
+  `--payload-file` holding a single *object*. The token binds
+  `(resource, id, verb)` and **nothing else**: `error-enrichment` + the rule id
+  (for `create`, the `integration_type:rank` pair) + the verb. **Field values are
+  not bound.** Hand-edit a `--description`, a `--pattern`, `--approved`, or the
+  contents of that object file and re-run with the same live token, and it still
+  redeems — what executes is then no longer what the plan the user approved
+  showed. If anything but the target changes after the plan, throw the token
+  away, re-run the plan step, and relay the new plan.
+- **Batch** — two or more targets, **or an array `--payload-file` of any length,
+  including one entry**. The token binds `error-enrichment-batch` + a sha256
+  prefix over a canonical form of the whole change: the targets **and**, for
+  `create` / `update`, the field values being written. (`delete` has no field
+  values, so its hash covers the sorted, deduped ids alone.) Editing the payload
+  file or the id list between plan and confirm invalidates the token — the re-run
+  fails the token check and prints a fresh plan instead of writing. Reordering
+  ids, or a formatter reordering JSON keys, does *not* invalidate it: the
+  canonical form is sorted at both levels.
+
+One confirm covers the whole set either way — the batch hash pins the payload, it
+does not add a second gate.
+
+## PATCH-omit semantics
+
+`update` is a PATCH — it changes only the fields you pass. Two consequences:
+omitting a field leaves it alone (so you can't accidentally blank a description),
+and the repeatable list flags can't *empty* a list, because "no `--resolution-step`
+given" and "an empty list" look identical on the command line. To clear
+`resolution_steps` or `examples`, pass the empty list explicitly:
+
+```bash
+echo '{"resolution_steps": []}' > /tmp/clear.json
+dr error-enrichments update 7 --payload-file /tmp/clear.json --server <S>
+```
+
+In array mode the same rule applies per entry:
+`[{"id": 7, "resolution_steps": []}]`.
+
+## How matching actually works (get this wrong and rules silently do nothing)
+
+Verified against `DataIntegrationErrorDescription.get_err_description`:
+
+1. Rules are scoped **per `integration_type`** and scanned in **`rank` order**
+   (rank 1 first). A rule only ever sees errors from its own vendor.
+2. Matching uses Python **`re.match`**, which anchors at the **start** of the
+   string. `INVALID_LOGIN` does *not* match `Error: INVALID_LOGIN` — write
+   `.*INVALID_LOGIN.*`. This is the single most common authoring mistake.
+3. Newlines are stripped from the error first (`"".join(err.splitlines())`), so
+   a multi-line error is matched as one long line. Don't write patterns
+   expecting `\n`.
+4. **A draft (unapproved) rule steals the hit counter but shows nothing.** The
+   highest-ranked matching rule gets the hit whether or not it is approved;
+   scanning then continues for an *approved* match. If only drafts matched, the
+   user sees **no explanation at all** while the hit count climbs. High hits +
+   `approved: false` is therefore an active user-facing gap, not a curiosity —
+   it is what `stats`' `needs_attention` list surfaces.
+5. `test-regex` runs the same `re.match` + newline-stripping server-side. Trust
+   it over local regex reasoning, and never hand-verify a pattern you could test.
+
+## Raw error sources on a tenant
+
+Three different `dr integrations` surfaces, and they are not interchangeable:
+
+| Command | Gives you |
+|---|---|
+| `integrations get <id> --server S` | the integration-level raw `error_description` |
+| `integrations query-status --query-id <qid>... --json --server S` | per-query `last_sync_error` — takes query ids, not an integration id (at least one `--query-id` is required), and **use `--json`**, the table truncates the error to 60 chars |
+| `integrations errors <id> --server S` | the *enriched* message the user currently sees (matched rule's description + steps) |
+
+`integrations status <id>` shows only status and last-run time — no error text;
+don't reach for it here.
+
+`integrations errors` printing *"no canned error explanation available"* is a
+direct signal that **no approved rule matched** for that integration — the
+single fastest per-tenant confirmation that a rule is missing.
+
+## Guard rails
+
+- **Reads are free; writes need the user.** Never run a mutation the user hasn't
+  approved in this conversation, and never on a prod server without walking the
+  plan output through them first.
+- **`import` is not an edit tool.** It replaces the whole table and zeroes every
+  counter. Fleet changes go through `update` / `create`; see
+  [safety-backup.md](safety-backup.md) for the policy.
+- **One server per mutation.** A batch is many rules on **one** server; there is
+  still no bulk write across servers — a fleet change is N confirmed runs, each
+  visible to the user.
+- **One confirm covers the whole batch.** The plan output is your last chance to
+  check the id list — read every id in it before handing back the token, because
+  nothing will stop at item three to ask again. A batch `delete` plan prints one
+  compact line per rule — `rule <id> (<type> r<rank>) hits N up N down N — <description>`
+  — so the whole blast radius, counters included, fits above the single Tier-A
+  challenge word instead of pushing it off the dialog.
+- **A token is not a licence to change the payload.** On a single-target write the
+  token binds the target only, so an edited field flag still redeems — see the
+  binding rules above and re-run the plan whenever the values move.
+- **A batch is not all-or-nothing.** It continues past a failed item and exits
+  non-zero; the summary table is the record of what actually landed. Never report
+  "done" from the exit code alone, and never re-run the whole batch blindly after
+  a partial failure.
+- **Ids are per-server.** An id list copied from another server's output points
+  at unrelated rules. Re-derive ids from a `list`/`get` against the server you
+  are about to write to.
+- **Never match rules across servers by `id`.** Key on
+  `(integration_type, re_pattern)`.
+- **Don't invent flags or subcommands.** Run `--help`; if it isn't there, it
+  doesn't exist.
+- **`--json` for anything you parse**, never the human tables.
+- **User-facing text is the product.** `description` and `resolution_steps` are
+  read by customers — get wording approved, and keep internal identifiers,
+  stack traces, and vendor jargon out of them.
+- **Credentials stay in the keychain.** Never echo JWTs or session ids.
+
+## Common mistakes
+
+| Mistake | Fix |
+|---|---|
+| Pattern without a leading `.*` | `re.match` anchors at the start — `.*NEEDLE.*` |
+| Assuming a draft rule is harmless | It steals the hit and shows the user nothing; approve it or lower its rank |
+| A general rule ranked above a specific one | The general one matches first and hides the better message — rank specific first |
+| Reverting with `import` | Wipes all rules and zeroes counters; revert per-rule with `create`/`update`/`delete` |
+| Matching rules across servers by `id` | Key on `(integration_type, re_pattern)` |
+| Reusing an id list from another server's output | Ids are per-server database ids — re-derive them against the target server |
+| Treating a non-zero batch exit as "nothing happened" | The run continues past failures; read the summary table for what landed |
+| Waiting for a summary table on a **one-entry** array payload | One target prints the single-rule success line and propagates its error verbatim — the table starts at two targets, even though the token binds as a batch |
+| Skimming the plan on a batch write | One confirm covers every id in it — verify the list, not the count |
+| Passing positional ids **or field flags** alongside an array `--payload-file` | Array mode carries every field inside each entry; pick one mode |
+| Parsing a batch `get --json` as an array of the ids you asked for | One id is a bare object, and failed ids are absent — read stderr + the exit code |
+| Reusing a live token after editing a field flag on a **single**-target write | Single targets bind `(resource, id, verb)` only; re-run the plan |
+| Expecting `--resolution-step` with no value to clear the steps | PATCH-omit semantics — clear with `--payload-file {"resolution_steps": []}` |
+| Writing a rule on one server and stopping | Reconcile the fleet — per-server drift is the problem this tooling exists to fix |
+| Skipping the backup because "it's one small change" | The backup is also the diff baseline; it costs one command per server |

package/dist/skills/dr-error-enrichment/reference/groundcover.md

@@ -0,0 +1,84 @@
+# Groundcover — mining errors that nothing matches
+
+The monolith logs every unmatched resolve with the marker
+`[ErrorEnrichment] No matching rule`. Read `get_gcql_reference` before composing
+queries — gcQL is not LogQL and not shell.
+
+## Find the lines
+
+Use a bare free-text keyword (it hits the full-text index;
+`content:*ErrorEnrichment*` forces a full scan and will time out on a busy env):
+
+```
+ErrorEnrichment | fields _time, content | limit 20
+ErrorEnrichment | stats count()
+```
+
+## The marker's payload is text, not fields
+
+The line carries `vendor_name`, `datasource_id`, `query_id`, `err_len`, and
+`err_sha256_prefix`, but they are printf-formatted **inside the log message** —
+they are not indexed log attributes. `stats by (vendor_name)` will not error, it
+will silently return one empty group. Extract them first:
+
+```
+ErrorEnrichment | extract_regexp "vendor_name=(?P<vendor>[^ ]+)" from content
+  | stats by (vendor) count() as unmatched | sort by (unmatched desc) | limit 20
+
+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
+```
+
+Group by `vendor` to see which connector has the biggest unmatched volume, and by
+`sig` to count *distinct* unmatched errors and rank the repeat offenders —
+identical prefixes are the same normalised error, so the top `sig` rows are your
+highest-value new rules. Widen the window with `_time:7d` only after a tight
+window proves the predicate returns rows.
+
+## The hash is deliberate
+
+`err_sha256_prefix` + `err_len` exist precisely so the raw error text stays out of
+the log — vendor errors can embed customer paths and tokens. Don't expect to
+recover the message from the marker.
+
+Get the **raw text** from a different source: the vendor sync error logs around
+the same timestamp / `datasource_id`, or the tenant itself via the surfaces in
+[core.md](core.md) (`integrations get <id>`, or
+`integrations query-status --query-id <qid> --json` for the `query_id` the marker
+names — that subcommand keys off query ids, not the integration id).
+
+Treat raw error text as customer data — use it to build the rule, keep it out of
+chat summaries beyond what the rule needs, and prefer sanitised text in
+`examples`.
+
+## Environment mapping
+
+Groundcover envs are not dr-cli server keys. Envs are `prod-us`, `prod-east-us`,
+`prod-west-us-2`, `prod-demo`, `prod-uk`, `prod-uk-south`,
+`prod-canada-central`.
+
+| dr-cli server | Groundcover env |
+|---|---|
+| `UK` | `prod-uk*` |
+| `CA` | `prod-canada-central` |
+| `DEMO` | `prod-demo` |
+| `US` / `US2` | **ambiguous** across `prod-us`, `prod-east-us`, `prod-west-us-2` |
+| `EU` | **unmapped** — resolve it before mining (see below) |
+
+`EU` was added to the registry after this table was written and its
+groundcover env has not been confirmed. Resolve it the same way as the US
+ambiguity before mining, and record the answer here once known.
+
+Resolve the US ambiguity with
+`ErrorEnrichment | stats by (env) count() | limit 100`, or ask. Never mine one
+region's logs to justify a rule you then only write to another.
+
+## Prove the pipeline before concluding zero
+
+An empty gcQL result is indistinguishable from a wrong env, too-narrow window, or
+misspelled field — none of those error, they all return nothing. Run a query you
+expect to return rows (`ErrorEnrichment | stats count()`) before reporting zero
+unmatched errors.
+
+Errors that already match a rule can be mined the same way, for `examples` and
+for validating a pattern change against real traffic.

package/dist/skills/dr-error-enrichment/reference/jira-bugs.md

@@ -0,0 +1,219 @@
+# Known bugs — is this error even the customer's problem?
+
+An enrichment rule is a message *to a customer* about something they can act on.
+Point one at a defect of ours and it does two kinds of damage: the customer is
+told to go fix something they cannot fix, and the defect stops looking like a
+defect — once an error reads as "explained", nobody escalates it again. A rule
+over our own bug is worse than no rule.
+
+So every candidate the improve pass ranks gets one question before it becomes a
+proposal: **is this error ours?** Jira is the check.
+
+## The field
+
+DR bugs carry a single-select **`System area`** — note the lowercase `a` —
+`customfield_10717`. Integration work is the option **`Integration`**, id
+`20748`, **singular**. There is no `Integrations` option, and a non-existent
+option value in JQL **returns zero rows instead of erroring** — so
+`"System Area" = "Integrations"` is indistinguishable from "no known bugs".
+Same discipline as gcQL: prove a query returns rows before believing a clean
+result.
+
+Three near-identically named dead fields exist — `System Area old`
+(`customfield_10654`), `System Area till April 22` (`customfield_10671`),
+`System Area for SF (Child Area)` (`customfield_10765`). Write `cf[10717]`; it is
+the one unambiguous form.
+
+Site: `datarailsteam.atlassian.net`, cloudId
+`a84c2098-d520-4c84-a5cf-a576c83ede6e`.
+
+## The sweeps
+
+**Open integration bugs** — the exclusion list (~20 rows at any time):
+
+```jql
+project = DR AND issuetype = Bug AND cf[10717] = "Integration"
+  AND statusCategory != Done ORDER BY created DESC
+```
+
+**Recently fixed ones** — just as disqualifying, and easier to miss:
+
+```jql
+project = DR AND issuetype = Bug AND cf[10717] = "Integration"
+  AND resolved >= -60d ORDER BY resolved DESC
+```
+
+A signature whose volume stops the week a fix shipped needs no rule at all.
+Compare the bug's `resolved` date against the last `_time` of the signature
+before writing anything.
+
+**Adjacent areas.** Sync failures also get filed under `Fileboxes` (`22505`) and
+`Data Mapper` (`20746`). Widen when the vendor or symptom points that way:
+`cf[10717] IN ("Integration", "Fileboxes", "Data Mapper")`.
+
+**Free-text pass — do not skip it.** `System area` is *optional* on the Bug
+create screen, so filtering on it under-counts by design: dozens of DR bugs a
+year are filed with the wrong area or none at all (20 with no area at all in the
+last 180 days). Before concluding a signature is unticketed, search the text with
+no area filter:
+
+```jql
+project = DR AND issuetype = Bug AND text ~ "connection was forcibly closed"
+  ORDER BY created DESC
+```
+
+`text ~` spans summary, description, comments **and** the `Bug Description`
+custom field, which is where CS-raised bugs actually keep the error body
+(`description` is usually `null` on them — see below). Strip ids, paths, numbers
+and quotes out of the phrase first; a phrase carrying a tenant-specific id
+matches nothing and reads as "no bug".
+
+Fetch light on all of these:
+`fields: ["key","summary","status","priority","created","resolutiondate"]`. A
+`*all` search over 20 DR bugs is mostly Salesforce account metadata and will
+blow the response limit.
+
+## Matching a signature to a bug
+
+Bugs record no error regexes, so this is judgement, not a join. Four signals:
+
+- **Vendor** — the connector named in the bug against the marker's
+  `vendor_name`.
+- **Symptom** — the bug's own error text. On CS-raised bugs it lives in
+  **`Bug Description` (`customfield_10720`)**, not `description`, which is
+  `null`; read both.
+- **Time** — first appearance of the `err_sha256_prefix` against the bug's
+  `created`. A signature that starts the week a bug was filed is very likely that
+  bug.
+- **Tenant** — the marker's `datasource_id` → org, against the bug's
+  `Customer Name` / `Business details`. A signature confined to one tenant that
+  already has a bug open is that bug; one spread across tenants usually is not.
+
+State which signal you matched on. "Probably DR-51612" with no reason is not a
+triage result.
+
+## The four verdicts
+
+| Verdict | Looks like | Do |
+|---|---|---|
+| **Customer- or vendor-side** | expired or revoked credentials, permission denied, deleted object, vendor rate limit, vendor outage, an ODBC/DSN condition on their machine | Propose a rule — the normal improve flow |
+| **Our defect, ticket exists** | matches an open or recently-fixed integration bug | **No rule.** Report the signature with the bug key and its volume — the volume is priority evidence the bug does not have yet |
+| **Our defect, no ticket** | our code raised it — see below | **No rule.** Flag it and offer to open a bug |
+| **Unclear whose fault** | plausible either way and no bug matches | **No rule.** Say what is ambiguous and what would settle it |
+
+**Whose code raised it is the whole distinction**, and error *shape* does not
+settle it. A Python traceback, an exception class, `NoneType` / `KeyError` /
+`IndexError`, a raw un-enriched exception body, a 5xx, a timeout — every one of
+these reaches us from vendors and from customer-side components too: a vendor API
+returning its own stack trace in the response body, an ODBC driver or the Database
+Sync Agent failing on the customer's own machine, a vendor SDK exception
+surfacing through our process. Those shapes are **clues that raise the question**,
+not the answer to it.
+
+Answer it from where the error was raised, not from what it looks like:
+
+- **The log source.** Which service and which module emitted the line, and is the
+  exception raised in our frame or caught from a vendor call?
+- **The host.** Our infrastructure, the vendor's, or the customer's machine — the
+  Sync Agent and ODBC/DSN conditions are the customer's.
+- **The endpoint.** A 500 from a vendor endpoint is *their* outage and a fine
+  thing to enrich; a 500 from a Datarails endpoint is ours.
+- **Internal ids or our own identifiers in customer-visible text** — that text was
+  composed by us, so the leak is ours regardless of what triggered it.
+
+If those signals don't converge, the verdict is **Unclear**, not "ours" — and not
+a rule either. Guessing "ours" suppresses a valid vendor-side rule; guessing
+"theirs" buries one of our defects.
+
+Two consequences worth saying out loud to the user: the unmatched-error pass is a
+**defect detector** at least as much as a rule generator, and a run that
+surfaces three bugs and no rules is a successful run, not an empty one.
+
+## Offering to open a bug
+
+Filing a Jira issue is outward-facing work. **Ask first, show the exact summary
+and body you intend to file, and wait for a yes.** Never file one per signature
+in a loop — related signatures are usually one bug, and one bug with four
+signatures listed is more useful to whoever picks it up than four thin tickets.
+
+`createJiraIssue` with `projectKey: "DR"`, `issueTypeName: "Bug"`, and
+`additional_fields`:
+
+| Field | Value |
+|---|---|
+| `customfield_10717` | `{"id": "20748"}` — **System area = Integration.** Optional on the create screen, which is why it gets forgotten: a bug filed without it is invisible to every sweep above, including the next improve run's own sweep |
+| `customfield_10683` | Environment DR — `{"id": "14663"}` Production (Development `14662`, Testing `14664`) |
+| `customfield_10682` | Severity — Minor `14658`, Medium `14659`, Major `14660`, Critical `14661` |
+| `priority` | `{"name": "P2"}` — **ask, do not pick.** Volume is evidence for a priority, not a priority |
+| `customfield_10720` | `Bug Description` — the body every DR bug is actually read from. Put the detail here, not only in `description` |
+
+Only `project`, `issuetype` and `summary` are enforced; everything else silently
+defaults to empty.
+
+Body content: vendor, groundcover env and window, the `err_sha256_prefix`, the
+unmatched volume, how many distinct `datasource_id`s are affected, first and last
+occurrence, and redacted error text.
+
+### Redaction is a step, not an adjective
+
+Nothing in the CLI sanitises this for you — you are pasting text into a ticket by
+hand, so the redaction happens in the draft you show the user, before
+`createJiraIssue` is called at all. Jira is a **wider** audience than this
+conversation, not a narrower one: the ticket is readable by the whole company and
+outlives the run, and the hash-only log marker
+([groundcover.md](groundcover.md)) exists precisely so this text does not spread.
+
+Walk the error text and remove every one of these before it goes in the body or
+`Bug Description`. If you cannot tell what a value is, it is customer data:
+
+| Remove | Replace with |
+|---|---|
+| Tokens, keys, passwords, connection strings, `Authorization` / cookie values, SAS URLs, anything after `pwd=` / `password=` / `apikey=` | `<redacted>` |
+| Usernames, email addresses, personal names | `<user>` |
+| Host names, IPs, DSNs, database and schema names, file paths, share and bucket names | `<host>` / `<path>` |
+| Customer identifiers — org and tenant names, account codes, GL account names and numbers, vendor object ids, invoice or entity numbers | `<id>` |
+| Row-level financial data of any kind — amounts, balances, dates tied to a customer's records | drop the fragment entirely |
+
+What survives is the part that is about *our code*: the exception class, the
+message template, the module and line, the vendor's own error code and its
+generic text. That is what the fix needs; the rest only widens exposure. Keep the
+`err_sha256_prefix` in the ticket — it is the stable handle that ties the ticket
+back to the signature without carrying any of this.
+
+Two identifiers that are deliberately fine to include, because they are ours and
+not customer content: the `err_sha256_prefix` and the `datasource_id`. Prefer a
+count of affected `datasource_id`s to a list of tenant names.
+
+`@mentions` need ADF. A markdown `@Name` renders as plain text and notifies
+nobody — pass `contentFormat: "adf"` with a real
+`{"type":"mention","attrs":{"id":"<accountId>"}}` node, or mention people in a
+follow-up comment.
+
+Then report the new key in the improve run's output, so the next run's sweep
+excludes the signature instead of re-proposing it.
+
+## No Jira access is not a clean sweep
+
+If the Atlassian tools are unavailable in the session, say so and mark the
+proposals **un-triaged**. Silently skipping the sweep and presenting a ranked
+proposal list is the failure this file exists to prevent — the list looks
+identical either way.
+
+## Pitfalls
+
+| Mistake | Fix |
+|---|---|
+| `cf[10717] = "Integrations"` | The option is singular `Integration`; a bad value returns **zero rows, no error** |
+| `"System Area" = …` | Three stale look-alike fields exist — use `cf[10717]` |
+| Only sweeping open bugs | A fix that shipped last week disqualifies the rule too — sweep `resolved >= -60d` |
+| Trusting the `System area` filter alone | It is optional on create and often wrong or empty — add a `text ~` pass with no area filter |
+| Searching a phrase that carries ids or paths | Strips to nothing useful — search the stable words only |
+| Reading `description` for the error text | CS-raised bugs leave it `null`; the body is `Bug Description` (`customfield_10720`) |
+| `fields: ["*all"]` on a bug sweep | Mostly Salesforce metadata, and it exceeds the response limit |
+| Calling it ours because it *looks* like a traceback, or theirs because it looks like a vendor message | Shape is a clue, not the verdict — settle it on the log source, the host and whose endpoint answered, and say **unclear** when they don't converge |
+| Pasting the error body into the ticket as-is | Redact first, in the draft you show the user — nothing in the CLI does it for you, and a Jira ticket is a wider audience than this conversation |
+| Writing a rule "so the customer sees something" while the bug is open | It buries the defect and blames the customer — report the signature against the bug instead |
+| Filing a bug without `System area` | The next sweep cannot see it; set `customfield_10717` |
+| Filing one bug per signature | Group related signatures into one, and only with the user's yes |
+| Pasting the raw error body into the ticket | Sanitise it — Jira is a wider audience than this chat |
+| Reporting "no unmatched errors worth a rule" after an un-run sweep | Say the sweep did not run; un-triaged is a different answer from clean |