tau-coding-agent 0.1.5 → 0.2.0

package/skills/github-pull-request/references/stewardship.md

@@ -0,0 +1,60 @@
+# Existing-PR stewardship
+
+Resume the existing PR within the requested scope and the [authorization matrix](../SKILL.md#authorization). Monitoring does not require repeating PR creation, and status-only or analysis requests do not authorize changes or publication.
+
+## Establish live context
+
+- Confirm GitHub CLI availability/authentication and identify the repository and PR. Fetch its current base, head SHA, draft state, metadata, checks, and review state.
+- Read applicable repository instructions and CI/review conventions. Consult templates and metadata conventions when changing copy, not as a prerequisite to every status check.
+- Track the current head. After each push, monitor the new head rather than carrying forward earlier results.
+- Before changing files or history, ensure the PR's actual head branch is checked out. Inspect the working tree, commits, and complete base-to-head diff, including the parent diff for a stacked PR. Preserve unrelated user work and honor changelog, generated-file, test, hook, and signing requirements.
+- Use the `git-commit` skill for new commits. Do not rewrite commits merely for cleanup. Never push the default branch.
+
+## CI and conflicts
+
+- Monitor required and pending checks, including automated-review checks.
+- Never infer success from command errors, missing status, or an earlier head.
+- Rerun clearly flaky or infrastructure-failed checks once, but flag them to the user.
+- Before any review feedback arrives, fold a small, clear CI fix into its originating commit when unambiguous. Use `--force-with-lease` if already pushed. Otherwise create a focused fix commit.
+- Assess large or unclear failures with the user before acting.
+- Resolve trivial base conflicts autonomously. Explain semantic or uncertain conflicts and stop. Changing an existing PR's base, closing it, or reopening it also requires a checkpoint.
+- Run focused validation before pushing stewardship code or conflict changes. Use `--force-with-lease` when an authorized branch update requires a force push.
+
+## Automated reviews
+
+Only clearly identified bots or GitHub Apps count as automated; otherwise feedback is human. Request or re-request automated reviewers when the repository workflow calls for it, not human reviewers without explicit authorization.
+
+Inspect review summaries and conversation comments. Fetch every unresolved inline thread, paginating when needed. Classify each automated finding:
+
+- **Valid**: correct, in scope, and worth fixing.
+- **Already addressed**: fixed by an existing branch commit.
+- **Deferred**: valid but out of scope for this PR.
+- **Dismissed**: incorrect, duplicate, or too low-value.
+- **Unclear**: needs judgment or more information.
+
+For valid or deferred findings requiring large, architectural, or scope-expanding changes—or any uncertain finding or fix—assess with the user and leave the feedback untouched.
+
+For small, clearly valid findings:
+
+1. Make one focused commit per finding, including any tests.
+2. Comments with one root cause may share a commit.
+3. Batch commits into one push to limit CI cycles.
+4. After pushing, reply briefly inline, link the fixing commit when useful, and resolve the thread.
+
+For remaining already addressed, deferred, or dismissed inline findings, reply briefly with the reason and resolve the thread.
+
+Avoid top-level responses unless strictly needed or expected by the repository. Never replace inline replies with a top-level summary.
+
+## Human reviews
+
+Investigate each human comment and recommend an action, but do not edit, reply, or resolve without explicit direction. When authorized, apply the same focused fix and validation rules. Reply or resolve only when instructions explicitly request it; authorization to implement a fix alone is insufficient.
+
+## Live metadata
+
+Treat the live PR as authoritative. Before editing its title or body, fetch the latest content, make the smallest edit through a file, then update and verify. Never overwrite manual edits from a stale draft. Beyond factual corrections, update copy only for material changes to scope or reviewer context, preserving user-supplied or approved copy. Append nothing to copy supplied exactly.
+
+Use descriptive labels only when commonly used on comparable PRs. Review/readiness or automation-triggering labels and human reviewer requests remain explicit-authorization actions.
+
+## Finish the current stage
+
+Continue authorized stewardship until the [readiness criteria](../SKILL.md#completion-readiness-and-merge-boundaries) are met or a checkpoint/blocker needs user input. Report pending or failed checks, unresolved feedback, or unavailable status honestly. Do not mark ready, enable auto-merge, or merge automatically. After the user marks ready, monitor newly triggered checks and reviews on the current head.

package/skills/oracle/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oracle
-description: Get a second opinion by bundling a prompt + a curated file set, then asking a strong model from a different family through a separate Pi invocation.
+description: "Get independent reviews, second opinions, or help getting unstuck by asking a strong model from another family with a curated prompt and file set."
 ---
 
 # Oracle
@@ -43,14 +43,14 @@ Run commands from this skill directory:
 ./scripts/oracle-bundle -p "<task>" --file "src/**" --file "!**/*.test.*"
 
 # Show which oracle model would be selected
-./scripts/oracle --list-models --current openai-codex/gpt-5.5
+./scripts/oracle --list-models --current openai-codex/gpt-6-astra
 
 # Ask the automatically selected oracle model
-./scripts/oracle --current openai-codex/gpt-5.5 \
+./scripts/oracle --current openai-codex/gpt-6-astra \
   -p "<task>" --file "src/**" --file "!**/*.test.*"
 
 # Override the oracle model when the automatic choice is wrong
-./scripts/oracle --model github-copilot/claude-opus-4.7 \
+./scripts/oracle --model anthropic/claude-fable-5 \
   -p "<task>" --file "src/**" --file "!**/*.test.*"
 ```
 

package/skills/oracle/scripts/oracle

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
 import path from "node:path";
-import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { fileURLToPath } from "node:url";
 
 const THINKING_LEVEL = "max";
@@ -114,6 +114,14 @@ function readSettings() {
   }
 }
 
+function getAgentDir() {
+  const configured = process.env.PI_CODING_AGENT_DIR;
+  if (!configured) return path.join(homedir(), ".pi", "agent");
+  if (configured === "~") return homedir();
+  if (configured.startsWith("~/")) return path.join(homedir(), configured.slice(2));
+  return path.resolve(configured);
+}
+
 function defaultModel(settings) {
   if (!settings.defaultProvider || !settings.defaultModel) return undefined;
   return normalizeModelSpec(`${settings.defaultProvider}/${settings.defaultModel}`);
@@ -144,82 +152,87 @@ function selectOracleModel(models, enabledModels, currentFamily) {
 
 function bestModelForFamily(models, enabledModels, family) {
   return models
-    .map((model) => ({ model, score: scoreModel(model, enabledModels, family) }))
-    .filter((entry) => entry.score >= 0)
-    .sort((a, b) => b.score - a.score || a.model.spec.localeCompare(b.model.spec))[0]?.model;
+    .filter((model) => modelFamily(model.spec) === family)
+    .sort((left, right) => compareModels(left, right, enabledModels, family))[0];
 }
 
-function scoreModel(entry, enabledModels, targetFamily) {
-  if (modelFamily(entry.spec) !== targetFamily) return -1;
-
-  let score = enabledModels.has(normalizeModelSpec(entry.spec)) ? 10_000 : 0;
-  score += providerScore(entry.provider, targetFamily);
-  score += nameScore(entry.model, targetFamily);
-  return score;
+function compareModels(left, right, enabledModels, family) {
+  return (
+    Number(enabledModels.has(normalizeModelSpec(right.spec))) -
+      Number(enabledModels.has(normalizeModelSpec(left.spec))) ||
+    modelRank(right.model, family) - modelRank(left.model, family) ||
+    providerRank(right.provider, family) - providerRank(left.provider, family) ||
+    left.spec.localeCompare(right.spec)
+  );
 }
 
-function providerScore(provider, family) {
+function providerRank(provider, family) {
   const normalized = provider.toLowerCase();
   if (family === "openai") {
-    if (normalized === "openai-codex") return 700;
-    if (normalized === "openai") return 600;
-    if (normalized === "github-copilot") return 500;
-    if (normalized.includes("azure")) return 450;
-    if (normalized === "openrouter") return 300;
-    return 100;
+    if (normalized === "openai-codex") return 5;
+    if (normalized === "openai") return 4;
+    if (normalized === "github-copilot") return 3;
+    if (normalized.includes("azure")) return 2;
+    if (normalized === "openrouter") return 1;
+    return 0;
   }
 
   if (family === "anthropic") {
-    if (normalized === "github-copilot") return 700;
-    if (normalized === "anthropic") return 600;
-    if (normalized === "amazon-bedrock") return 450;
-    if (normalized === "openrouter") return 300;
-    return 100;
+    if (normalized === "github-copilot") return 4;
+    if (normalized === "anthropic") return 3;
+    if (normalized === "amazon-bedrock") return 2;
+    if (normalized === "openrouter") return 1;
+    return 0;
   }
 
   if (family === "google") {
-    if (normalized === "google") return 600;
-    if (normalized === "github-copilot") return 500;
-    if (normalized.includes("vertex")) return 450;
-    if (normalized === "openrouter") return 300;
-    return 100;
+    if (normalized === "google") return 4;
+    if (normalized === "github-copilot") return 3;
+    if (normalized.includes("vertex")) return 2;
+    if (normalized === "openrouter") return 1;
+    return 0;
   }
 
   return 0;
 }
 
-function nameScore(model, family) {
+function modelRank(model, family) {
   const normalized = model.toLowerCase();
 
   if (family === "openai") {
-    if (/gpt-5\.5/.test(normalized)) return 1_000;
-    if (/gpt-5\.4/.test(normalized)) return 950;
-    if (/gpt-5\.3.*codex/.test(normalized)) return 925;
-    if (/gpt-5\.3/.test(normalized)) return 900;
-    if (/gpt-5\.2/.test(normalized)) return 850;
-    if (/gpt-5\.1/.test(normalized)) return 800;
-    if (/gpt-5/.test(normalized)) return 750;
-    if (/gpt-4\.1/.test(normalized)) return 500;
-    return 100;
+    if (/gpt-6[-_.]astra/.test(normalized)) return 11;
+    if (/gpt-5\.6[-_.]sol/.test(normalized)) return 10;
+    if (/gpt-5\.6/.test(normalized)) return 9;
+    if (/gpt-5\.5/.test(normalized)) return 8;
+    if (/gpt-5\.4/.test(normalized)) return 7;
+    if (/gpt-5\.3.*codex/.test(normalized)) return 6;
+    if (/gpt-5\.3/.test(normalized)) return 5;
+    if (/gpt-5\.2/.test(normalized)) return 4;
+    if (/gpt-5\.1/.test(normalized)) return 3;
+    if (/gpt-5/.test(normalized)) return 2;
+    if (/gpt-4\.1/.test(normalized)) return 1;
+    return 0;
   }
 
   if (family === "anthropic") {
-    if (/claude[-_.]opus[-_.]4[-_.]7/.test(normalized)) return 1_000;
-    if (/claude[-_.]opus[-_.]4[-_.]6/.test(normalized)) return 950;
-    if (/claude[-_.]opus[-_.]4[-_.]5/.test(normalized)) return 900;
-    if (/claude[-_.]opus[-_.]4[-_.]1/.test(normalized)) return 850;
-    if (/claude[-_.]opus[-_.]4/.test(normalized)) return 800;
-    if (/claude[-_.]sonnet[-_.]4[-_.]6/.test(normalized)) return 700;
-    if (/claude[-_.]sonnet[-_.]4[-_.]5/.test(normalized)) return 650;
-    if (/claude[-_.]sonnet[-_.]4/.test(normalized)) return 600;
-    return 100;
+    if (/claude[-_.]fable[-_.]5/.test(normalized)) return 10;
+    if (/claude[-_.]opus[-_.]4[-_.]8/.test(normalized)) return 9;
+    if (/claude[-_.]opus[-_.]4[-_.]7/.test(normalized)) return 8;
+    if (/claude[-_.]opus[-_.]4[-_.]6/.test(normalized)) return 7;
+    if (/claude[-_.]opus[-_.]4[-_.]5/.test(normalized)) return 6;
+    if (/claude[-_.]opus[-_.]4[-_.]1/.test(normalized)) return 5;
+    if (/claude[-_.]opus[-_.]4/.test(normalized)) return 4;
+    if (/claude[-_.]sonnet[-_.]4[-_.]6/.test(normalized)) return 3;
+    if (/claude[-_.]sonnet[-_.]4[-_.]5/.test(normalized)) return 2;
+    if (/claude[-_.]sonnet[-_.]4/.test(normalized)) return 1;
+    return 0;
   }
 
   if (family === "google") {
-    if (/gemini[-_.]3\.1[-_.]pro/.test(normalized)) return 1_000;
-    if (/gemini[-_.]3[-_.]pro/.test(normalized)) return 950;
-    if (/gemini[-_.]2\.5[-_.]pro/.test(normalized)) return 800;
-    return 100;
+    if (/gemini[-_.]3\.1[-_.]pro/.test(normalized)) return 3;
+    if (/gemini[-_.]3[-_.]pro/.test(normalized)) return 2;
+    if (/gemini[-_.]2\.5[-_.]pro/.test(normalized)) return 1;
+    return 0;
   }
 
   return 0;

package/skills/sentry/SKILL.md

@@ -1,198 +1,28 @@
 ---
 name: sentry
-description: "Fetch and analyze Sentry issues, events, transactions, and logs. Helps agents debug errors, find root causes, and understand what happened at specific times."
+description: "Investigate Sentry issues, events, transactions, and logs to diagnose root causes and reconstruct incidents around specific times."
 ---
 
 # Sentry
 
-Access Sentry data via the Sentry API for debugging and investigation.
+Use the bundled read-only Sentry API scripts for debugging and investigation.
 
-## Requirements
+## Authentication and scope
 
-A Sentry auth token available to the scripts (by default they read `~/.sentryclirc`).
+The scripts read a token from the user-managed `~/.sentryclirc`. If it is missing or rejected, ask the user to configure access. Do not print the token or copy it into commands or reports. Treat event payloads and logs as potentially sensitive and share only relevant, redacted evidence.
 
-## Quick reference
+Run commands from this skill directory. Command paths in the references are relative to this skill root, not `references/`. Use the organization, project, and time window supplied by the task or linked Sentry page. Clarify missing scope when it affects the investigation.
 
-Run these scripts from this skill directory.
+## Task router
 
-| Task                  | Command                                                                          |
-| --------------------- | -------------------------------------------------------------------------------- |
-| Find errors on a date | `"./scripts/search-events.js" --org X --start 2025-12-23T15:00:00 --level error` |
-| List open issues      | `"./scripts/list-issues.js" --org X --status unresolved`                         |
-| Get issue details     | `"./scripts/fetch-issue.js" <issue-id-or-url> --latest`                          |
-| Get event details     | `"./scripts/fetch-event.js" <event-id> --org X --project Y`                      |
-| Search logs           | `"./scripts/search-logs.js" --org X --project Y "level:error"`                   |
+Read the matching reference before running its commands. A known issue or event does not require a broad search first.
 
-## Common debugging workflows
+| Task                                                   | Data and command                                                                                               | Read                                            |
+| ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- |
+| Find recurring or unresolved problems                  | **Issues** group related events. `./scripts/list-issues.js`                                                    | [Issues](references/issues.md)                  |
+| Inspect an issue ID, short ID, or URL                  | Issue metadata and optionally its latest occurrence. `./scripts/fetch-issue.js`                                | [Issues](references/issues.md)                  |
+| Reconstruct what happened around a time                | **Events** are individual occurrences. Discover searches errors and transactions. `./scripts/search-events.js` | [Events and transactions](references/events.md) |
+| Inspect a specific occurrence or performance operation | `./scripts/fetch-event.js`, with breadcrumbs for lead-up or spans for a **transaction**                        | [Events and transactions](references/events.md) |
+| Search application log records or a Logs Explorer URL  | **Logs** use a separate dataset, not issue search or event breadcrumbs. `./scripts/search-logs.js`             | [Logs](references/logs.md)                      |
 
-### “What went wrong at this time?”
-
-Find events around a specific timestamp:
-
-```bash
-# Find all events in a 2-hour window
-"./scripts/search-events.js" --org myorg --project backend \
-  --start 2025-12-23T15:00:00 --end 2025-12-23T17:00:00
-
-# Filter to just errors
-"./scripts/search-events.js" --org myorg --start 2025-12-23T15:00:00 \
-  --level error
-
-# Find a specific transaction type
-"./scripts/search-events.js" --org myorg --start 2025-12-23T15:00:00 \
-  --transaction process-incoming-email
-```
-
-### “What errors have occurred recently?”
-
-```bash
-# List unresolved errors from last 24 hours
-"./scripts/list-issues.js" --org myorg --status unresolved --level error --period 24h
-
-# Find high-frequency issues
-"./scripts/list-issues.js" --org myorg --query "times_seen:>50" --sort freq
-
-# Issues affecting users
-"./scripts/list-issues.js" --org myorg --query "is:unresolved has:user" --sort user
-```
-
-### “Get details about a specific issue/event”
-
-```bash
-# Get issue with latest stack trace
-"./scripts/fetch-issue.js" 5765604106 --latest
-"./scripts/fetch-issue.js" https://sentry.io/organizations/myorg/issues/123/ --latest
-"./scripts/fetch-issue.js" MYPROJ-123 --org myorg --latest
-
-# Get specific event with all breadcrumbs
-"./scripts/fetch-event.js" abc123def456 --org myorg --project backend --breadcrumbs
-```
-
-### “Find events with a specific tag”
-
-```bash
-# Find by custom tag (e.g., thread_id, user_id)
-"./scripts/search-events.js" --org myorg --tag thread_id:th_abc123
-
-# Find by user email
-"./scripts/search-events.js" --org myorg --query "user.email:*@example.com"
-```
-
----
-
-## Fetch issue
-
-```bash
-"./scripts/fetch-issue.js" <issue-id-or-url> [options]
-```
-
-Get details about a specific issue (grouped error).
-
-**Accepts:**
-
-- Issue ID: `5765604106`
-- Issue URL: `https://sentry.io/organizations/sentry/issues/5765604106/`
-- New URL format: `https://myorg.sentry.io/issues/5765604106/`
-- Short ID: `JAVASCRIPT-ABC` (requires `--org`)
-
-**Options:**
-
-- `--latest` include the latest event with full stack trace
-- `--org <org>` organization slug (for short IDs)
-- `--json` output raw JSON
-
----
-
-## Fetch event
-
-```bash
-"./scripts/fetch-event.js" <event-id> --org <org> --project <project> [options]
-```
-
-**Options:**
-
-- `--org, -o <org>` organization slug (required)
-- `--project, -p <project>` project slug (required)
-- `--breadcrumbs, -b` show all breadcrumbs (default: last 30)
-- `--spans` show span tree for transactions
-- `--json` output raw JSON
-
----
-
-## Search events (Discover)
-
-```bash
-"./scripts/search-events.js" [options]
-```
-
-**Time range options:**
-
-- `--period, -t <period>` relative time (24h, 7d, 14d)
-- `--start <datetime>` start time (ISO 8601: 2025-12-23T15:00:00)
-- `--end <datetime>` end time (ISO 8601)
-
-**Filter options:**
-
-- `--org, -o <org>` organization slug (required)
-- `--project, -p <project>` project slug or ID
-- `--query, -q <query>` Discover search query
-- `--transaction <name>` transaction name filter
-- `--tag <key:value>` tag filter (repeatable)
-- `--level <level>` level filter (error, warning, info)
-- `--limit, -n <n>` max results (default: 25, max: 100)
-- `--fields <fields>` comma-separated fields to include
-
-**Query syntax (Discover):**
-
-```
-transaction:process-*     Wildcard transaction match
-level:error               Filter by level
-user.email:foo@bar.com    Filter by user
-environment:production    Filter by environment
-has:stack.filename        Has stack trace
-```
-
----
-
-## List issues
-
-```bash
-"./scripts/list-issues.js" [options]
-```
-
-**Options:**
-
-- `--org, -o <org>` organization slug (required)
-- `--project, -p <project>` project slug (repeatable)
-- `--query, -q <query>` issue search query
-- `--status <status>` unresolved, resolved, ignored
-- `--level <level>` error, warning, info, fatal
-- `--period, -t <period>` time period (default: 14d)
-- `--limit, -n <n>` max results (default: 25)
-- `--sort <sort>` date, new, priority, freq, user
-- `--json` output raw JSON
-
----
-
-## Search logs (Logs Explorer)
-
-```bash
-"./scripts/search-logs.js" [query|url] [options]
-```
-
-**Options:**
-
-- `--org, -o <org>` organization slug (required unless URL provided)
-- `--project, -p <project>` filter by project slug or ID
-- `--period, -t <period>` time period (default: 24h)
-- `--limit, -n <n>` max results (default: 100, max: 1000)
-- `--json` output raw JSON
-
----
-
-## Tips
-
-1. Start broad (time window + simple query), then drill into a single event/issue.
-2. Use `--breadcrumbs` on `fetch-event.js` for the full lead-up to an error.
-3. Use `list-issues.js --sort freq` to find recurring problems.
-4. Use tags (`request_id`, `user_id`, etc.) to correlate events.
+Correlate by timestamp, project, environment, and request/trace/user tags where available. Report evidence separately from hypotheses. Empty results are limited to the selected dataset, filters, time range, and result limit, not proof that no incident occurred. Authentication/API failures are not empty results.

package/skills/sentry/references/events.md

@@ -0,0 +1,79 @@
+# Sentry events and transactions
+
+Run commands from the Sentry skill root. An event is an individual occurrence. Discover can search error events and transactions. Transactions describe performance operations and can carry spans. Neither search is a Logs Explorer query.
+
+## Investigate a time window
+
+Start with the relevant project and a bounded window, then narrow by transaction, level, or correlation tags. Use explicit ISO 8601 timezone offsets or `Z` to avoid an ambiguous incident time.
+
+```bash
+# Events in a two-hour window
+"./scripts/search-events.js" --org myorg --project backend \
+  --start 2025-12-23T15:00:00Z --end 2025-12-23T17:00:00Z
+
+# Errors since a known time
+"./scripts/search-events.js" --org myorg --start 2025-12-23T15:00:00Z --level error
+
+# A transaction name
+"./scripts/search-events.js" --org myorg --project backend \
+  --period 24h --transaction process-incoming-email
+
+# Correlate by custom tag or user
+"./scripts/search-events.js" --org myorg --tag thread_id:th_abc123
+"./scripts/search-events.js" --org myorg --query "user.email:*@example.com"
+```
+
+Retain event IDs and project context, then fetch the occurrences that support the incident timeline. Matching a transaction name does not by itself establish whether a returned record is an error or transaction. Inspect the event details. For application log records, read `references/logs.md` from the skill root.
+
+### Search options
+
+```bash
+"./scripts/search-events.js" [options]
+```
+
+| Option                    | Meaning                                                                                  |
+| ------------------------- | ---------------------------------------------------------------------------------------- |
+| `--org, -o <org>`         | Organization slug, required                                                              |
+| `--project, -p <project>` | Project slug or numeric ID                                                               |
+| `--period, -t <period>`   | Relative range such as `1h`, `24h`, `7d`, or `14d`. Defaults to `24h` without `--start`. |
+| `--start <datetime>`      | Absolute start. Takes precedence over `--period`.                                        |
+| `--end <datetime>`        | Absolute end with `--start`. If omitted, end is now. Do not use `--end` alone.           |
+| `--query, -q <query>`     | Discover search query                                                                    |
+| `--transaction <name>`    | Transaction name filter                                                                  |
+| `--tag <key:value>`       | Tag filter, repeatable                                                                   |
+| `--level <level>`         | Level filter such as `error`, `warning`, or `info`                                       |
+| `--limit, -n <n>`         | Maximum results, default 25, capped at 100                                               |
+| `--fields <fields>`       | Comma-separated field names                                                              |
+| `--json`                  | Raw JSON                                                                                 |
+
+Default fields are `id,title,timestamp,transaction,message`. The request also includes `project.name`. Use `--json` to inspect returned project context or add fields explicitly, for example `--fields "id,title,timestamp,project.name,user.email"`.
+
+Discover query examples:
+
+```text
+transaction:process-*     Wildcard transaction match
+level:error               Filter by event level
+user.email:foo@bar.com     Filter by user
+environment:production    Filter by environment
+has:stack.filename        Has a stack trace
+```
+
+Results are newest first. The script fetches one limited result set without automatic pagination. Narrow a busy time window rather than treating the first page as a complete timeline.
+
+## Fetch an exact event
+
+```bash
+"./scripts/fetch-event.js" abc123def456 --org myorg --project backend --breadcrumbs
+"./scripts/fetch-event.js" abc123def456 --org myorg --project backend --spans
+```
+
+| Option                    | Meaning                                                   |
+| ------------------------- | --------------------------------------------------------- |
+| `<event-id>`              | Required positional event ID, not an issue ID or trace ID |
+| `--org, -o <org>`         | Organization slug, required                               |
+| `--project, -p <project>` | Project slug, required                                    |
+| `--breadcrumbs, -b`       | All available breadcrumbs instead of the last 30          |
+| `--spans`                 | Display transaction spans, up to 50 in formatted output   |
+| `--json`                  | Raw event JSON                                            |
+
+Use breadcrumbs for the lead-up to an error and spans for transaction operations. Formatted output is selective, including abbreviated stack traces. Use `--json` when needed for omitted details, and share only relevant, redacted fields. Timestamp rendering differs between search and detail output, so normalize to a stated timezone when assembling a timeline.

package/skills/sentry/references/issues.md

@@ -0,0 +1,62 @@
+# Sentry issues
+
+Run commands from the Sentry skill root. Issues group related events and summarize recurrence, affected users, and status. Use them to prioritize recurring problems or inspect a known group, not as a substitute for the exact event in an incident window.
+
+## Inspect a known issue
+
+```bash
+"./scripts/fetch-issue.js" 5765604106 --latest
+"./scripts/fetch-issue.js" https://sentry.io/organizations/myorg/issues/123/ --latest
+"./scripts/fetch-issue.js" https://myorg.sentry.io/issues/123/ --latest
+"./scripts/fetch-issue.js" MYPROJ-123 --org myorg --latest
+```
+
+Accepts a numeric issue ID, either URL format above, or a short ID such as `JAVASCRIPT-ABC`. Short IDs require `--org`.
+
+| Option        | Meaning                                                                 |
+| ------------- | ----------------------------------------------------------------------- |
+| `--latest`    | Include the latest event, exception stack trace, and recent breadcrumbs |
+| `--org <org>` | Organization slug for short IDs                                         |
+| `--json`      | Raw issue JSON, or `{ issue, event }` when combined with `--latest`     |
+
+The latest event may be outside the requested incident window. For a specific occurrence, read `references/events.md` from the skill root and search/fetch that event instead. Formatted output abbreviates stack traces, breadcrumbs, tags, and request bodies. Use raw JSON only when the omitted detail is needed, and redact sensitive fields before reporting.
+
+## List and search issues
+
+```bash
+# Recent unresolved errors
+"./scripts/list-issues.js" --org myorg --project backend \
+  --status unresolved --level error --period 24h
+
+# High-frequency issues
+"./scripts/list-issues.js" --org myorg --query "times_seen:>50" --sort freq
+
+# Issues affecting users
+"./scripts/list-issues.js" --org myorg --query "is:unresolved has:user" --sort user
+```
+
+| Option                    | Meaning                                                               |
+| ------------------------- | --------------------------------------------------------------------- |
+| `--org, -o <org>`         | Organization slug, required                                           |
+| `--project, -p <project>` | Project slug or numeric ID, repeatable                                |
+| `--query, -q <query>`     | Sentry issue search query                                             |
+| `--status <status>`       | `unresolved`, `resolved`, or `ignored`                                |
+| `--level <level>`         | `error`, `warning`, `info`, or `fatal`                                |
+| `--period, -t <period>`   | Time period, default `14d`                                            |
+| `--limit, -n <n>`         | Maximum results, default 25, capped at 100                            |
+| `--sort <sort>`           | `date` (last seen), `new` (first seen), `priority`, `freq`, or `user` |
+| `--json`                  | Raw JSON                                                              |
+
+Issue search examples:
+
+```text
+is:unresolved             Unresolved issues
+has:user                  Has user context
+user.email:*@example.com  User email pattern
+lastSeen:-24h             Seen in the last 24 hours
+firstSeen:>=2025-12-23     First seen on or after a date
+times_seen:>50            More than 50 occurrences
+error.handled:0           Unhandled errors
+```
+
+Combine filters in a quoted query and narrow by project when known. This script returns one limited result set and does not paginate automatically. Record the scope and limit before drawing conclusions about prevalence.

package/skills/sentry/references/logs.md

@@ -0,0 +1,46 @@
+# Sentry logs
+
+Run commands from the Sentry skill root. Logs Explorer records are a separate dataset from Discover events and grouped issues. Event breadcrumbs are not a replacement for searching application logs.
+
+## Search logs or use a Logs Explorer URL
+
+```bash
+"./scripts/search-logs.js" "level:error" --org myorg --project backend
+"./scripts/search-logs.js" "message:*timeout*" --org myorg --period 7d
+"./scripts/search-logs.js" "trace:abc123" --org myorg --project backend
+"./scripts/search-logs.js" "https://myorg.sentry.io/explore/logs/?project=123&statsPeriod=7d"
+```
+
+Quote queries and URLs so the shell does not interpret wildcards or `&`. URLs can use `https://myorg.sentry.io/explore/logs/` or `https://sentry.io/organizations/myorg/explore/logs/`.
+
+The script extracts organization, the first `project` parameter, `statsPeriod`, and `logsQuery` from a URL. It does not preserve every UI filter, absolute `start`/`end`, or multiple project selections. Put explicit option overrides after the URL and check the resulting scope before relying on it.
+
+### Options
+
+```bash
+"./scripts/search-logs.js" [query|url] [options]
+```
+
+| Option                    | Meaning                                                 |
+| ------------------------- | ------------------------------------------------------- |
+| `--org, -o <org>`         | Organization slug, required unless extracted from a URL |
+| `--project, -p <project>` | Project slug or ID, added as a `project:` query filter  |
+| `--period, -t <period>`   | Relative time range, default `24h`                      |
+| `--limit, -n <n>`         | Maximum results, default 100, capped at 1000            |
+| `--json`                  | Raw JSON                                                |
+
+There are no `--start`, `--end`, or `--query` options on this script. Supply the query positionally. For an incident at a specific time, choose a relative period that includes it and verify returned timestamps. If this cannot represent the required scope, report the limitation instead of silently treating a different time range as equivalent.
+
+Query examples supported by the script's help:
+
+```text
+level:error                     Log severity
+message:*timeout*               Message text
+trace:abc123                    Trace ID
+project:backend                 Project filter
+level:error message:*failed*    Combined filters
+```
+
+Results are newest first and contain `sentry.item_id`, `trace`, `sentry.severity`, `timestamp`, and `message`. Formatted output shows timestamp, severity, message, and trace when present. Use `--json` for the returned item ID and structured fields.
+
+The script fetches one limited result set, without automatic pagination. Narrow the query or period to investigate busy streams. Correlate traces and timestamps with events as needed by reading `references/events.md` from the skill root. Empty logs do not rule out an error event, an issue, or missing log instrumentation.