--- name: error-resolve description: Read the error-patrol ledger, check each linked task's current status via the task store, and resolve the corresponding Sentry issue once its gating task has reached deployed/done. Never resolves on merged or pr_open. --- # Error Resolve Read `state/error-patrol-ledger.json`'s `taskLinks` entries (written by `/error-fix`), look up each linked task's **current** status via the task store, and call Sentry's issue-resolve endpoint for any issue whose gating task has reached `deployed` or `done`. This skill makes **no code changes** and queues no tasks — it only reads the ledger/task store and mutates Sentry issue state (plus the ledger entry, once the Sentry call succeeds). This skill hardcodes Sentry as the backend (no provider abstraction) — see `planning/error-patrol/PLAN.md` for the rationale, same as `/error-scan` and `/error-fix`. --- ## Setup: Parse Arguments Before starting, check if any flags were passed: - `--dry-run` — run the full check (task-store status lookups, gating decision per issue) but make **no Sentry mutation** and **no ledger write**. Print what would have been resolved instead. --- ## Step 0: Preconditions 1. Confirm `SHIPWRIGHT_TASK_STORE_URL` and `SHIPWRIGHT_TASK_STORE_TOKEN` are set in the environment. If either is missing, print: ``` error-resolve requires SHIPWRIGHT_TASK_STORE_URL and SHIPWRIGHT_TASK_STORE_TOKEN to be set. Invoke /shipwright:task-store for setup instructions. Skipping resolve. ``` and stop. Do not touch the ledger or Sentry. 2. Confirm `SENTRY_ORG` and `SENTRY_AUTH_TOKEN` are set (`echo "org=$SENTRY_ORG token_set=$([ -n "$SENTRY_AUTH_TOKEN" ] && echo yes || echo no)"`). If either is unset or empty, print: ``` error-resolve requires SENTRY_ORG and SENTRY_AUTH_TOKEN to be set in the environment. Skipping resolve. ``` and stop. 3. All Sentry API calls in this skill use: ```bash curl -sS -H "Authorization: Bearer $SENTRY_AUTH_TOKEN" "https://sentry.io/api/0/..." ``` and the resolve call additionally sends `-X PUT -H "Content-Type: application/json" -d '{"status": "resolved"}'`. Never print `$SENTRY_AUTH_TOKEN`, never write it to any file, and never echo the literal value of `$SENTRY_ORG` into a comment or log line that could get pasted somewhere persistent — always reference these as their env var names in output and in this file. 4. All task-store calls use: ```bash curl -sf -H "Authorization: Bearer $SHIPWRIGHT_TASK_STORE_TOKEN" \ "$SHIPWRIGHT_TASK_STORE_URL/tasks/{id}" ``` Never print or persist `$SHIPWRIGHT_TASK_STORE_TOKEN`. --- ## Step 1: Read the Ledger The ledger lives at `state/error-patrol-ledger.json` — **one level up from the repo checkout, in agent workspace state, not tracked inside this repo** (same tier as `state/entropy-patrol-last-run.json`; sibling of the repo checkouts, same path-resolution convention as `/error-scan`'s Step 5 and `/error-fix`'s Step 9). 1. If the file does not exist, print: ``` No state/error-patrol-ledger.json found. Nothing to resolve. ``` and stop cleanly. This is a normal outcome (error-scan/error-fix haven't run yet, or nothing has ever been queued), not a fatal error. 2. If it exists, read and parse it. If it has no top-level `taskLinks` key, or `taskLinks` is an empty object, print: ``` No taskLinks entries in the ledger. Nothing to resolve. ``` and stop cleanly — also not an error. 3. Otherwise, collect every ` -> {primary, companion}` entry from `taskLinks` for processing in Step 2. Recall the shape (written by `/error-fix`'s Step 9): ```json { "taskLinks": { "": { "primary": "", "companion": "" } } } ``` --- ## Step 2: Determine the Gating Task Per Issue For each `taskLinks` entry, decide which task's status actually gates resolution of that Sentry issue. **Design decision (documented here, not just implicit in the logic):** - If `primary` is **non-null**, the primary task is the actual fix for the issue's underlying bug — landing it is what makes the Sentry issue itself go away. **Gate resolution on the primary task's status alone.** The companion task (if present) is a separate, independent observability improvement at the same call site, not a fix for the reported error — its status **never blocks or gates** resolution, even if it's still pending or HITL long after the primary fix has shipped. - If `primary` is **null** (the pure-noise case — the issue only ever got a companion task, no primary fix task exists), there is no other task to gate on. **Gate resolution on the companion task's status instead**, since it's the only task associated with that issue. So: **gating task = `primary` if non-null, else `companion`.** If `primary` is null and `companion` is also absent (should not normally happen given `/error-fix`'s Step 9, but treat defensively), there is no task to check status on at all — skip that issue this run, noting it in the summary as "no linked task to check." --- ## Step 3: Query the Task Store for Each Gating Task's Current Status **CRITICAL (acceptance criterion 1): query the task store for the CURRENT status of every gating task before taking any Sentry action.** The ledger itself never stores task status — it only stores task IDs — so this is always a live lookup on this run, never a cached value. For each issue's gating task ID from Step 2: ```bash curl -sf -H "Authorization: Bearer $SHIPWRIGHT_TASK_STORE_TOKEN" \ "$SHIPWRIGHT_TASK_STORE_URL/tasks/{gating_task_id}" ``` - **200** — record the returned task's `status` field for use in Step 4. - **404** — the task no longer exists (deleted, or outside this token's scope). Record this issue as `missing` for Step 4/the summary — **do not treat as ready to resolve.** Don't crash the run; continue with the next issue. - Any other non-2xx (e.g. 401, 5xx) — record this issue as a lookup failure for the summary (distinct from `missing`) and continue with the next issue; do not abort the whole run over one failed lookup. If the gating task's status is `cancelled`, treat it the same as `missing` for gating purposes: **not ready to resolve.** A cancelled task means the fix was abandoned, not shipped — resolving the Sentry issue would be wrong. Record it as `cancelled` (distinct from `missing`) in the summary so a human can see why that issue is stuck. --- ## Step 4: Decide Readiness Per Issue **CRITICAL (acceptance criterion 2): an issue resolves only when its gating task (Step 2) has reached `deployed` or `done` status — never `merged`, never `pr_open`, never any other status.** For each issue with a successfully-looked-up gating task status (Step 3): - Gating task status is `deployed` or `done` → **ready to resolve.** - Gating task status is anything else (`pending`, `in_progress`, `pr_open`, `approved`, `merged`, `deploying`, `blocked`, or any other non-terminal/non-`deployed`/non-`done` value) → **not ready.** Record the blocking status for the summary (Step 8) so a human can see exactly what's still pending. `merged` and `pr_open` are explicitly **not** sufficient even though they're further along than `pending` — the task must have actually shipped (`deployed`) or been marked fully complete (`done`), not merely merged into the base branch or opened as a PR. - Gating task was `missing` (404) or `cancelled` (Step 3) → **not ready.** Included in the summary under a distinct "missing/cancelled" bucket, not conflated with "not yet ready." - Gating task lookup failed for another reason (non-404 error) → **not ready**, included under a distinct "lookup failed" bucket for the summary. Retry on a future run. Issues classified as anything other than "ready to resolve" are left completely untouched this run — no Sentry call, no ledger write for them. --- ## Step 5: Dry-Run Output (if --dry-run) If `--dry-run` was passed, skip Step 6 (Sentry mutation) and Step 7 (ledger write) entirely. For every issue classified as "ready to resolve" in Step 4, print what would have happened: ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ERROR RESOLVE — DRY RUN ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Would resolve {N} Sentry issues: — gating task {task_id} status={deployed|done} Would leave {N} issues untouched (not yet ready): — gating task {task_id} status={status} {N} issues skipped (missing/cancelled gating task): — gating task {task_id} ({missing|cancelled}) No Sentry calls made. No ledger changes. Re-run without --dry-run to resolve. ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ``` Stop after printing. --- ## Step 6: Call the Sentry Resolve Endpoint Skip this step entirely if `--dry-run` was passed (handled in Step 5). For each issue classified as "ready to resolve" in Step 4: ```bash curl -sS -X PUT \ -H "Authorization: Bearer $SENTRY_AUTH_TOKEN" \ -H "Content-Type: application/json" \ -d '{"status": "resolved"}' \ "https://sentry.io/api/0/organizations/$SENTRY_ORG/issues/{issue_id}/" ``` This call uses the `event:write` scope already granted on `SENTRY_AUTH_TOKEN` (same token `/error-scan` and `/error-fix` use for read calls — no separate token needed). Treat the call as successful only if **both**: 1. The HTTP response is 2xx, **and** 2. The response body's `status` field is `"resolved"` (parse the JSON response and check — don't assume success from the status code alone). If either condition fails, treat this issue's resolve as **failed** this run: - Do not proceed to Step 7 for this issue — its ledger entry is left completely untouched. - Record the failure (issue ID + whatever error detail is available: HTTP status, response body) for the Step 8 summary. - Continue processing the remaining ready issues — one failed resolve call does not abort the run. --- ## Step 7: Update the Ledger (Only After a Successful Resolve) **CRITICAL (acceptance criterion 3): only mutate an issue's ledger entry after its Step 6 Sentry resolve call has succeeded.** Never touch the ledger for an issue before or in place of a successful Sentry call — if the call fails or is skipped, that issue's `taskLinks` entry (and its `issues` entry, if present) is left exactly as-is for a future run to retry. Skip this step entirely if `--dry-run` was passed. **Ledger mutation approach (documented decision):** for each issue that was successfully resolved in Step 6, remove that issue's entry from the top-level `taskLinks` map entirely. Rationale: once an issue is resolved in Sentry, there is nothing further for `error-resolve` to track for it — `taskLinks` exists solely to let this skill find issues that still need a resolve check, so a resolved issue's entry is stale weight, not useful history. (This mirrors `/error-scan`'s own `issues` map, which separately already tracks a `"status": "resolved"` transition for the general issue history — this skill does not duplicate that; it only owns `taskLinks`.) If the issue also has an entry under the ledger's top-level `issues` map (owned by `/error-scan`), leave that alone — this skill never touches `issues`, `lastRun`, or `serviceRepoMap`. This is a **partial merge, not a full overwrite** — same discipline as `/error-fix`'s Step 9: 1. Read the current on-disk ledger fresh (in case it changed since Step 1, e.g. a concurrent `/error-fix` run added new links). 2. Remove only the specific `taskLinks` keys for issues resolved in Step 6 this run. 3. Leave every other top-level key (`lastRun`, `issues`, `serviceRepoMap`) and every other `taskLinks` entry that wasn't resolved this run completely untouched. 4. Write the updated ledger back to `state/error-patrol-ledger.json`. 5. Print: `Ledger updated: state/error-patrol-ledger.json (taskLinks entries cleared for resolved issues)` If the ledger write itself fails (e.g. disk error), log the failure. The Sentry issue is already resolved at this point (Step 6 succeeded before this step ran) — do not attempt to "unresolve" it to compensate. A missed `taskLinks` cleanup just means this issue's now-stale entry gets re-checked (and found already resolved, or simply produces a redundant no-op resolve call) on a future run; note this in the summary as a ledger-write failure distinct from a Sentry-call failure. --- ## Step 8: Print Summary Whether or not `--dry-run` was passed, always print a summary to stdout after the run (dry-run uses Step 5's format instead of this one): ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ERROR RESOLVE COMPLETE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Ledger entries checked: {N} RESOLVED {N} issues NOT YET READY {N} issues MISSING/CANCELLED gating task: {N} issues LOOKUP FAILED {N} issues (task-store error, retry next run) SENTRY CALL FAILED {N} issues (retry next run) {If any resolved:} Resolved: — gating task {task_id} reached {deployed|done} {If any not yet ready:} Not yet ready: — gating task {task_id} still {status} {If any missing/cancelled:} Missing/cancelled gating task (not resolved): — gating task {task_id} ({missing|cancelled}) {If any lookup failures:} Task-store lookup failed (retry next run): — gating task {task_id}: {error detail} {If any Sentry call failures:} Sentry resolve call failed (ledger untouched, retry next run): — {HTTP status / error detail} {If --dry-run: "Dry run — no Sentry calls made, no ledger changes."} {Else: "Ledger updated: state/error-patrol-ledger.json"} ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ``` Stop after printing — this is the sole final output. --- ## Error Handling - **Missing `SHIPWRIGHT_TASK_STORE_URL`/`SHIPWRIGHT_TASK_STORE_TOKEN` or `SENTRY_ORG`/ `SENTRY_AUTH_TOKEN`**: handled in Step 0 — print the message and stop without touching anything. - **Ledger missing, or missing/empty `taskLinks`**: handled in Step 1 — print a clean "nothing to resolve" message and stop. Not a fatal error. - **Gating task 404 or `cancelled`**: handled in Step 3/4 — not ready to resolve, recorded distinctly in the summary, run continues with remaining issues. - **Task-store lookup fails for another reason (401, 5xx)**: handled in Step 3 — recorded as a distinct lookup failure, run continues; retry on a future run. - **Sentry resolve call fails (non-2xx or response `status` isn't `"resolved"`)**: handled in Step 6 — that issue's ledger entry is left completely untouched, the failure is recorded in the summary, and the run continues with remaining ready issues. - **Ledger write fails after a successful Sentry resolve**: handled in Step 7 — log the failure, do not attempt to reverse the Sentry resolve; note it in the summary as a ledger-write failure. --- ## Constraints (Do Not Violate) - **Always a live task-store lookup.** Every gating task's status is queried fresh via `GET /tasks/:id` on this run (Step 3) before any Sentry action is taken. The ledger never stores task status and is never trusted as a status cache. - **Only `deployed`/`done` gates resolution.** `merged` and `pr_open` — and every other status — are explicitly insufficient. Never call the Sentry resolve endpoint for an issue whose gating task hasn't reached `deployed` or `done`. - **Primary gates over companion.** When an issue has both a `primary` and a `companion` task, only the `primary` task's status gates resolution — the companion is a separate observability improvement, not the fix, and its status never blocks or unblocks resolution. Only when `primary` is `null` (pure-noise, companion-only case) does the companion's status become the gate. - **Never mutate the ledger before the Sentry call succeeds.** An issue's `taskLinks` entry is only touched (removed) after its Step 6 resolve call has returned success (2xx **and** response `status: "resolved"`). A failed or skipped Sentry call always leaves that issue's ledger entry untouched for a future retry. - **Ledger update is a partial merge.** Only the resolved issues' `taskLinks` entries are removed. `lastRun`, `issues`, `serviceRepoMap`, and every other `taskLinks` entry are read fresh and written back untouched. - **Never log or persist `$SENTRY_AUTH_TOKEN` or `$SHIPWRIGHT_TASK_STORE_TOKEN`.** Not in the ledger, not in stdout output, not in any file. - **No hardcoded org, service, or repo names.** `$SENTRY_ORG` is read from the environment at runtime and never written literally into this file or into any output. - **No code changes, no task queueing.** This skill only reads the ledger/task store and mutates Sentry issue state (plus the ledger, post-success). It never opens a PR, never writes to the task store, and never queues new tasks — that's `/error-fix`'s job. - **`--dry-run` mutates nothing.** No Sentry PUT call, no ledger write. Everything that would happen is printed to stdout instead. - **One failure doesn't abort the run.** A 404/cancelled gating task, a task-store lookup error, or a failed Sentry call for one issue is recorded in the summary and the run continues processing the remaining issues.