eshu

Use when reviewing Eshu diffs, PRs, self-reviews, pre-push work, merge-readiness, graph/Cypher changes, runtime recovery changes, cassette/golden updates, generated artifacts, or performance evidence.

Drive one or more Eshu GitHub issues (including epics) to a verifiable closed state — merged PRs, a severity-tagged review gate, and resolution of every bot and human review (codex, GitHub Copilot, Cursor, Claude, and human reviewers, treated uniformly). ACTIVATE when the user says "drive issue(s)", "work issue(s) to closed/done", "close out issue/epic", or "finish #NNNN until merged", or sets a /goal referencing this skill. Pass one or more issue numbers or URLs as args; epics are expanded to their children automatically. Scoped to this repository (eshu-hq/eshu) and routes only to the Eshu project skills under .agents/skills/.

Use when writing, reviewing, debugging, or optimizing Cypher for Neo4j, NornicDB, or graph-backed application work, including graph schema design, graph indexes and constraints, MATCH, MERGE, UNWIND, query plans, graph write performance, graph read performance, graph-backed API/query handlers, materialization jobs, projection code, migrations, and backend portability.

Use for Eshu runtime diagnostics, reducer throughput work, graph backend diagnosis, local or CI proof runs, queue/shared projection analysis, or ADR evidence updates. Add `eshu-performance-rigor` whenever the work makes or validates a latency, throughput, resource, or wall-time claim; add Go, Cypher, concurrency, or correlation skills for those surfaces.

Use for Eshu performance investigations, benchmarks, query or index optimization, queue/reducer throughput changes, cold-bootstrap timing, scaled replays, full-corpus proofs, and before/after performance claims. Enforces a staged proof ladder, comparable run manifests, correctness and concurrency proof, remote preflight, and honest end-to-end classification.

Use when designing, debugging, refactoring, or reviewing Eshu workers, queues, leases, transactions, retries, batching, fan-out/fan-in, shared state, lock ordering, database writes, or distributed coordination where deadlocks, races, contention, starvation, or unsafe overlap may exist.

Use when calling Eshu MCP/API tools, debugging local Eshu MCP connectivity, designing or reviewing MCP tool schemas, or running graph-backed query tools where scope, pagination, timeout, stale local owner ports, truth labels, or payload size affect correctness and performance.

Use when writing, reviewing, debugging, or optimizing Eshu Postgres SQL, schema DDL, indexes, migrations, queue claims, liveness/readiness/status queries, transactions, lock waits, pg_stat_activity output, or relational performance diagnostics.

Use when a change adds a shell script that produces a generated artifact and commits it to the repo: a JSON schema, a Grafana dashboard, a verifier-generated file, a manifest, a fixture catalogue, a typed-API definition, or any other file whose committed form is a function of source-of-truth data plus a deterministic transformation. Activate for new scripts under `scripts/` that emit files under `docs/`, `go/internal/*/data/`, `deploy/`, or any checked-in artifact directory. Captures the three-file pattern (slim `generate-*.sh` + `lib/` chunks + `test-generate-*.sh` mirror), idempotency as a first-class test case, and the 500-line cap pre-planned rather than retrofitted.

Use when a change touches `go/internal/telemetry/instruments.go`, `go/internal/telemetry/contract.go` or any `contract_*.go`, the contract doc at `docs/public/observability/telemetry-coverage.md`, the public operator reference at `docs/public/reference/telemetry/index.md`, the static-analysis verifier `scripts/verify-telemetry-coverage.sh`, the CI workflow `.github/workflows/verify-telemetry-coverage.yml`, the operator dashboard `docs/public/observability/dashboards/eshu-operator-overview.json`, or when adding a new `eshu_dp_*` metric or a new pipeline stage. Also activate when investigating an operator report of "the metric we expect isn't there". Captures the Epic X discipline: the four-artifact contract (X1 doc + X2 verifier + X3 CI gate + X4 dashboard), the `No-Observability-Change:` marker discipline, the contributor runbook, and a pointer to the "Limitations Of The X2 Gate" section so future maintainers know what the verifier does and does not catch.

Use when changing Eshu workload admission, deployable-unit correlation, materialization, deployment tracing, service/repository story synthesis, or query truth where positive, negative, ambiguous, graph, and API evidence must all agree before the change is considered correct.

Use when a Go directory's README.md or doc.go drifts from the code, when a stale-marker line appears in .eshu-doc-state/stale.jsonl, when the user asks to update a package README, regenerate folder docs, document a new package, or after touching code under go/ where the package contract changed. Works the same under Claude Code and Codex. Keeps the README + doc.go pair current with the actual package surface, splits content by audience, and runs the humanizer pass before finalizing.

Eshu release, versioning, and open-source deployment pipeline. Use when releasing Eshu, bumping the Helm chart, publishing Docker images or CLI binaries, checking version mismatches, or coordinating image tag, chart version, appVersion, GHCR, OCI, and GitHub Release work.

Use when adding or changing a fact kind, changing a payload shape, editing sdk/go/factschema or sdk/go/collector, editing specs/fact-kind-registry.v1.yaml, editing fixture packs, or touching anything where an Odù (fixture-pack entry) overlaps a cassette or the B-12 snapshot. Encodes the Contract System v1 rules: typed structs over hand-built maps, version shims that live in the contracts module and never in reducer handlers, and the major/minor/patch break policy for payload schemas.

Use when changing, reviewing, testing, or documenting Go code in Eshu, including parser work, runtime services, storage adapters, query handlers, package APIs, test additions, and Go docs tied to code changes.

Resolve unresolved GitHub PR review threads after their referenced code has been fixed in the latest commit. Use this skill right after pushing changes that address reviewer feedback on an Eshu PR, so threads do not linger open on the conversation tab. The skill takes a PR number, classifies each unresolved thread as `fixed`, `unchanged`, or `ambiguous` against the current HEAD, and only auto-resolves the `fixed` ones. The rest stay open with a structured report. Treats every reviewer uniformly — codex, GitHub Copilot, Claude (when present), and human reviewers — by reading the comment body and checking the cited file:line, not by trusting the bot label.

Use when changing anything the B-7 golden-corpus gate asserts — collector fact emission, reducer/projector graph writes, correlation/materialization output, query or MCP tool response shapes, fact-kind or schema constants, or a new verb/edge/node/correlation — and when editing the cassettes (testdata/cassettes/), the B-12 snapshot (testdata/golden/e2e-20repo-snapshot.json), or scripts/verify-golden-corpus-gate.sh, or when the golden-corpus gate goes red. The cassettes plus the snapshot are Eshu's golden standard; a code change that alters projected truth without updating them in the same change fails the gate.

Debug and modify Eshu's security-scan workflow (.github/workflows/security-scan.yml): the Trivy filesystem/image, gosec, govulncheck, and nancy gates. ACTIVATE when editing security-scan.yml, bumping the Go toolchain (the `go` directive in go/go.mod) or a security dependency, or when any of those jobs (Trivy fs, Trivy image, gosec, govulncheck, nancy) is red (or red only in CI but green locally). Captures the Go-1.26 x/tools breakage, the trivy-action SARIF severity trap, the #nosec / gosec exit behavior, and — most important — the rule that you MUST reproduce with the exact CI tool version and flags, because a local approximation will lie to you.

A recipient can run eshu evidence bundle validate against a redacted evidence_bundle.v1. The bundle is share-safe; reproduce handles point at bounded CLI/API/MCP calls the recipient can run against their own instance. Profiles are local_lightweight, local_authoritative, local_full_stack, or production. A profile row marked unsupported MUST return `unsupported_capability`. Truth ceilings live in specs/capability-matrix.v1.yaml and go/internal/query/contract.go. Every fragment's default rendering works in local_lightweight and local_authoritative profiles without a configured LLM provider. LLM augmentation is policy-gated. llm:no-provider is a first-class status, not an error. Eshu's operating order is fixed: accuracy, then performance, then concurrency. An agent MUST prove correctness before proving speed. The active collector set is whatever is enabled in the active runtime profile. Per-collector MCP tools are enumerated from the live capability catalog, not from a static prose list. The fragment renders diff