Guidewire CI/CD Pipeline

Overview

Ship Gosu changes from a developer's branch to production without breaking running policies. Guidewire Cloud Console (GCC) deployment slots are the carrier-side promotion mechanism — dev → uat → prod — with config packages as the unit of promotion. The CI side validates compile, runs GUnit, and packages; the CD side promotes packages through slots with deploy-time gates.

Five production failures this skill prevents:

1. Bypassed compile/test gates — a gradle build failure on a developer's machine reaches CI as "works on my machine"; CI runs the same gates as a clean clone, fails fast, never lands on a slot.
2. Promotion without UAT regression — UW logic change goes dev → prod skipping UAT; the change interacts badly with a product line not exercised in dev; bound policies start showing wrong premium.
3. Schema change without rollback plan — a Gosu interface adds a required field; rolling back the deploy is fine, but rolling back the database column requires a separate migration that may have been forgotten.
4. Canary that isn't a canary — "canary" deploy serves 100% of traffic immediately because the slot router has no per-slot routing; a real canary needs traffic split, not just a separate slot.
5. Rollback after policies bound on the new code — a defective rate-plan deploy bound 200 policies in the 30 minutes before detection; reverting the code does not unbind the policies; they need targeted endorsement-correction or rate adjustment.

Prerequisites

• A working Guidewire Studio + runServer setup per guidewire-local-dev-loop
• GCC tenant with at least three slots (dev, uat, prod) configured for the integration's product line
• A CI runner (GitHub Actions, GitLab CI, Jenkins) with JDK 17 and access to a private artifact registry for config packages
• An age private key (per guidewire-security-and-rbac) provisioned to CI for decrypting environment-specific secrets

Instructions

Build the pipeline in this order. Each step targets one of the five production failures listed in Overview.

1. PR-time gates (run on every push)

Three checks, all blocking. The PR cannot merge to main if any fails.

# .github/workflows/ci.yml
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-java@v4
        with: { java-version: 17, distribution: temurin }
      - run: ./gradlew compileGosu                       # gate 1: code compiles
      - run: ./gradlew test                              # gate 2: GUnit passes
      - run: ./gradlew c…

Guidewire PolicyCenter Workflow

Overview

Drive the PolicyCenter policy lifecycle through Cloud API and survive the state-transition failures that derail naive automation. This is the workflow used by broker portals to quote-and-bind, by CRMs to push submissions, and by renewal jobs to issue out-of-cycle. Assumes guidewire-install-auth provides the bearer token and guidewire-sdk-patterns provides the retrying client with checksum round-trip.

Five production failures this skill prevents:

1. Bind on a quote with open UW issues — quote API returns 200, the underwritingIssues[] array is non-empty, the client ignores it, bind returns 422 rule-violation.
2. Bind on a stale quote — quotes expire (default 30 days). A submission left open over a holiday returns 422 quote-expired on bind.
3. Orphaned submissions on partial failure — submission → quote succeeds, bind fails, no rollback; the submission sits in Quoted status forever, blocking the next attempt.
4. Renewal outside the renewal window — calling renewal before the window opens (typically 60–90 days before expiration) returns 422 renewal-window-closed.
5. Endorsement premium drift — mid-term endorsement recalculates premium against current rate plans, which may differ from the rate plan in force at policy inception. The numeric difference surprises downstream finance integrations.

Prerequisites

• A working auth + SDK layer per guidewire-install-auth and guidewire-sdk-patterns (getToken(), patchResource(), paginate(), mapError())
• Cloud API roles pc.account.write, pc.submission.write, pc.policy.write assigned to the integration's Service Application
• Knowledge of which product code drives the workflow (e.g., PersonalAuto, BOPLine) — submission shape is product-specific
• For renewal jobs: read access to the renewal-window configuration on the relevant product

Instructions

Build the workflow as discrete state-transition functions, each fully responsible for surfacing the failure modes of its transition. Compose them with explicit checkpoints — never collapse the pipeline into a single fire-and-forget call.

1. Create the account

const idempotencyKey = crypto.randomUUID();
const account = await retryable(async () => {
  const res = await fetch(`${BASE}/pc/rest/v1/accounts`, {
    method: "POST",
    headers: { Authorization: `Bearer ${await getToken()}`, "Content-Type": "application/json", "Idempotency-Key": idempotencyKe…

Guidewire ClaimCenter Workflow

Overview

Drive the ClaimCenter claims lifecycle through Cloud API and survive the failure modes that derail naive automation. This is the workflow used by FNOL portals, IVR claims intake, partner-of-record APIs, and reserve-setting jobs. Assumes guidewire-install-auth provides the bearer token and guidewire-sdk-patterns provides the retrying client with checksum round-trip.

Five production failures this skill prevents:

1. Duplicate FNOL from multi-source intake — the same loss event is reported by the caller, the claimant, and the broker; without dedup logic three claims land on the same loss with three reserves.
2. Payment before reserve — code creates a payment without first setting a reserve in the matching cost category; API returns 422 reserve-required.
3. Authorization-tier violation — an integration with payment role cc.payment.write attempts a payment above its authorization limit; API returns 422 authorization-required and the payment lands in pending-approval.
4. Premature settlement — claim closed before all open reserves are zeroed or all open activities resolved; reopens compound work and generate audit findings.
5. Reopen vs. new claim confusion — late-arriving evidence on a closed claim creates a new claim with a different number, breaking the loss-event continuity downstream finance and analytics depend on.

Prerequisites

• A working auth + SDK layer per guidewire-install-auth and guidewire-sdk-patterns
• Cloud API roles cc.claim.write, cc.reserve.write, cc.payment.write assigned per least privilege; payment authorization tier matches the integration's expected payment range
• Knowledge of the carrier's loss-cause code list (AUTO, PROPERTY, WORKERSCOMP, etc.) and cost-category configuration (body, parts, medical, legal)
• A loss-dedup key strategy (typically: policyNumber + lossDate + lossCause + reporterId)

Instructions

1. FNOL with deduplication

Before creating a claim, check whether one already exists for the same loss event. The dedup key combines policy, loss date, loss cause, and the reporting party.

async function findExistingClaim(policyNumber: string, lossDate: string, lossCauseCode: string): Promise<Claim | null> {
  const url = `${BASE}/cc/rest/v1/claims?filter=policyNumber+eq+'${policyNumber}'+and+lossDate+eq+'${lossDate}'+and+lossCause.code+eq+'${lossCauseCode}'`;
  const res = await fetch(url, { headers: { Authorization: `Bearer ${await getToken(…

Guidewire Install & Auth

Overview

Authenticate a backend service to a Guidewire Cloud tenant using OAuth2 client credentials and operate the auth layer in production. This is not a hello-world walkthrough; it is the auth code your service runs at 3am when a token expires mid-batch, when a tenant admin rotates a scope, when a private CA renews a cert, and when on-call needs to swap a leaked secret without dropping in-flight requests.

The four production failures this skill prevents:

1. Token expiry storms — every request races to refresh, the Hub rate-limits the auth endpoint, the integration cascades to red.
2. Scope drift — a GCC admin removes a scope, every cached token starts returning 403, retrying does not help.
3. PKIX path building failed — JVM cannot validate the tenant's TLS chain because the private CA is not in the trust store; common when carriers front Cloud API with their own DLP appliance.
4. Secret rotation downtime — the active client secret is rotated and the old secret stops working before the new one is loaded; in-flight token refreshes fail until restart.

Prerequisites

• JDK 17 (Guidewire Cloud release 202503 and later)
• A registered Service Application in Guidewire Cloud Console (GCC) with Cloud API roles assigned per least privilege
• Network egress from your runtime to *.guidewire.net (runtime APIs) and gcc.guidewire.com (console only)
• A secret store the runtime can read at startup and on rotation signal (AWS Secrets Manager, GCP Secret Manager, HashiCorp Vault, or Kubernetes Secret with CSI driver)
• For private-CA tenants: the carrier's CA chain in PEM form

Instructions

Build the auth layer in this order. Each section solves one production failure mode; do not skip steps because the failure shows up in production, not in dev.

1. Implement the token-cache pattern below — proactive refresh, single-flight gate, JWT-based expiry.
2. Wire secret rotation to your secret store; do not commit secrets or bake them into images.
3. For private-CA tenants, install the trust store at the JVM/init-container layer.
4. Validate scope hardening on every refresh so drift fails fast, not on the next business call.

Token-cache pattern (production)

Tokens are short-lived, typically one hour. Reactive refresh on 401 is wrong: it doubles latency on the failing request and creates a thundering herd when many requests notice expiry simultaneously. Cache the token in-process and refresh proactively at 80% of TTL, behind a single-flight gate so concurrent refreshers serialize.

…

Guidewire Local Dev Loop

Overview

Run a local InsuranceSuite instance and iterate on Gosu rule logic in seconds, not minutes. The single biggest productivity killer in Guidewire development is paying the 5–15 minute gradle runServer cold-start cost on every change because the developer does not know which edits hot-reload and which force a restart.

Three production problems this skill prevents:

1. Restart cascade — developer changes a Gosu rule, restarts runServer, waits 8 minutes, finds the rule was wrong, repeats. A full day disappears in restarts.
2. Silent stale code — Studio claims it hot-reloaded a class but the running JVM is still executing the old bytecode (common when interfaces change). Tests pass against stale code.
3. GUnit drift — unit tests for Gosu rules diverge from the rules themselves because the cycle to run a single test through Studio is too slow; developers stop writing them.

Prerequisites

• JDK 17 (for Cloud release 202503+)
• Guidewire Studio installed (IntelliJ-based, distributed by Guidewire)
• Local InsuranceSuite configuration zone (PolicyCenter, ClaimCenter, or BillingCenter)
• ≥16 GB RAM on the dev machine — runServer + Studio + the JVM debug agent need headroom
• Sample data loader configured for the chosen product (e.g., PersonalAuto for PC)

Instructions

Build the inner loop in this order. Every step targets one of the three productivity killers above.

1. Start runServer once, keep it warm

Cold start takes 5–15 minutes; treat it as a session investment.

# Start in dev mode with debug agent on 8088, leaves the server attached to the terminal
./gradlew runServer -Pdebug=true -PdebugPort=8088 -Dgw.servermode=dev

gw.servermode=dev enables the hot-reload paths inside the JVM. debugPort=8088 exposes the JDWP debug agent — attach IntelliJ to it once and leave it. Restart only when the what hot-reloads table below says you must.

2. What hot-reloads, what does not

Memorize this table — it determines whether the next edit costs 0 seconds or 8 minutes.

Guidewire Migration and Upgrade

Overview

Move a Guidewire deployment without losing policies, claims, integrations, or trust. Two related but distinct workflows:

• Migration: on-prem InsuranceSuite → Guidewire Cloud (or one cloud tenant → another). Different infrastructure, different config-layer assumptions, different API surfaces.
• Upgrade: in-place version bump (e.g., release 202403 → 202503). Same infrastructure, new code, new APIs, deprecated APIs to retire.

Both are heavy lifts that go badly if executed without rehearsal. Five production failures this skill prevents:

1. Config reconciliation gaps — on-prem carries 5 years of customizations; cloud tenant ships with newer base config; cutover deploys the on-prem config and breaks because base assumptions diverged.
2. Deprecated-API blind spots — version upgrade removes a Cloud API that an integration depended on; the integration starts returning 404 the moment the upgrade lands.
3. No mid-flight rollback — cutover starts at midnight, fails at 2am, decision is "abort or push through"; without a pre-defined abort path the team chooses badly.
4. Data migration that loses optimistic-locking history — claims migrate but checksum values do not; downstream integrations fail every PATCH for a week until checksums regenerate.
5. Communication misalignment — brokers told "use the new system Monday" while the old system is still authoritative for in-flight quotes; bound state lives in two systems.

Prerequisites

• Approved migration / upgrade plan with named owners for: config reconciliation, data migration, integration cutover, communication, rollback authorization
• A staging tenant on the target platform (cloud) or target version that is exact-replica of production minus customer data
• Production-shape sample dataset for rehearsal (anonymized but representative volumes and shapes)
• Cutover window scheduled with documented blackout period for non-essential changes
• For upgrades: Guidewire's release notes for every version between current and target; deprecated API list for the target release

Instructions

Build the migration / upgrade plan in this order. Each step targets one of the five production failures listed in Overview.

1. Inventory the current state

Before designing the move, know what is actually deployed:

Guidewire Observability and Incident Response

Overview

Run a production Guidewire Cloud API integration with the dashboards, alerts, and runbooks an on-call engineer can act on at 3am. This skill consolidates the operational layer: what to measure, what to alert on, how to triage the top five incident classes, and how to close the loop with a post-incident review that prevents recurrence rather than performing root-cause theater.

Five operational failures this skill prevents:

1. Vanity dashboards — graphs of total request count, no per-endpoint p99, no SLI burn rate; on-call sees green during a real outage because the right thing was never measured.
2. Alert fatigue — every transient 5xx pages someone; in three weeks the team mutes the channel; a real incident two weeks later goes unnoticed for an hour.
3. No triage tree — on-call wakes up to "401 spike", does not know whether to rotate a secret, restart the integration, or call GCC; loses 20 minutes Googling.
4. Skipped post-incident review — the same root cause produces three incidents in a quarter because no one wrote down the action items from the first one.
5. Common-errors table living in nine Slack threads — operators cannot find the recovery for an error they have seen before, ask the same question in #ops, the answer takes 45 minutes.

Prerequisites

• A working integration emitting structured logs and metrics to a backend (Datadog, Grafana+Prometheus, New Relic, Splunk, or equivalent)
• Access to a paging system (PagerDuty, Opsgenie, VictorOps) with on-call rotations defined
• The integration_audit table from guidewire-security-and-rbac populated — incident triage depends on knowing what the integration tried to do
• correlation_id propagated end-to-end through every Cloud API call

Instructions

Build the operational layer in this order. Each step targets one of the five operational failures listed in Overview.

1. Define SLIs that measure user-visible behavior

Track what users care about, not what is easy to measure. For a Guidewire integration, the SLIs that matter:

Guidewire SDK Patterns

Overview

Build the Cloud API request layer that runs in production. This skill assumes the auth layer from guidewire-install-auth is in place — bearer tokens come from the cached token provider, not a static API_KEY. What this layer adds: safe mutations under optimistic locking, retry-aware writes, quota-friendly request pacing, complete pagination, and a typed error surface that business logic can pattern-match.

Five production failures this skill prevents:

1. 409 Conflict storms — client GETs a record, lets the user (or workflow) edit it, then PATCHes back without the latest checksum; the next concurrent edit causes both PATCHes to lose.
2. 429 cascades — every retry on 429 happens at the same backoff, all clients hammer the endpoint together, the tenant rate quota stays pinned.
3. Silent data loss in pagination — client treats pageSize=100 as "all results"; misses page 2 onward; reports inflated coverage to downstream.
4. Duplicate writes on retry — POST to create-claim times out at the load balancer, client retries, two claims land with the same FNOL.
5. Generic error handling — every non-2xx response collapses into "request failed", losing the userMessage, errors[].type, and attributes structure the API actually returns.

Prerequisites

• A working auth layer per guidewire-install-auth — getToken() returning a cached, scope-validated bearer
• Cloud API endpoints reachable on [TENANT].guidewire.net (PC/CC/BC base URLs in env)
• Node 20+ or equivalent runtime supporting fetch, AbortController, and crypto.randomUUID
• Familiarity with the Cloud API response envelope (data[], attributes, checksum, links) — see guidewire-install-auth/references/API_REFERENCE.md

Instructions

Implement the patterns below as composable layers on top of fetch. Each pattern targets one of the five production failures listed in Overview; do not skip any layer in production code.

1. Checksum round-trip for safe mutations

Every Cloud API resource carries a checksum. PATCH and PUT must echo the latest checksum in the request body, or the API returns 409 Conflict to protect concurrent writers. Wrap mutations in a fetch-then-mutate helper that does the round-trip automatically.

export async function patchResource<T>(path: string, mutate: (current: T) => Partial<T>): Promise<T> {
  const token = await getToken();
  const getRes = await fetch(`${BASE}${…

Guidewire Security and RBAC

Overview

Build the security posture an integration needs in production: secrets that cannot leak from the repo, roles that cannot escalate beyond their job, logs that cannot exfiltrate PII, and an audit trail that satisfies SOC 2 and NAIC Model Audit Rule reviewers. This skill is the application of generic security practice to the specific shape of Guidewire Cloud API — claim and policy data carry regulated PII; a leaked client_secret can read or write a carrier's entire book of business; carriers operate under state-level insurance regulator scrutiny.

Five real-world failures this skill prevents:

1. Plaintext .env in the repo — a git push to a public mirror leaks live credentials; the only defense is to never have plaintext in the tree, full stop.
2. Over-scoped Service Application — every integration starts with pc.account.write "to make development easier" and is never narrowed; the audit finding cites OWASP A01 broken access control.
3. PII in observability — console.log(claim) dumps SSN, DOB, claim narrative, and phone numbers into the logging pipeline, where they replicate to every downstream tool the company uses.
4. No audit trail of what the integration did — security review asks "what did this service touch in the last 90 days" and the answer is "everything in the access log, but we cannot tell which actor"; the audit fails.
5. Cross-tenant data bleed — a multi-tenant integration uses one set of credentials per environment instead of per tenant; a bug in tenant routing leaks Carrier A's data into Carrier B's response.

Prerequisites

• A working auth + SDK layer per guidewire-install-auth and guidewire-sdk-patterns
• sops and age installed locally (brew install sops age / apt install sops / mise install age)
• Access to GCC for the integration's Service Application configuration
• A logging/observability stack the integration writes to (Datadog, Splunk, ELK, or similar) — required for the redaction patterns to apply

Instructions

Build the posture in this order. Each layer addresses one of the five failures listed in Overview.

1. Encrypted committed secrets via SOPS + age

Plaintext .env files committed to a repo are the single largest source of credential leaks in the SaaS world. SOPS + age allows secrets to live in the repo as ciphertext that only holders of the age private key can read. The audit trail of "who rotated what when" comes free with git log.

sops-init                                    # writes .sops.y…

Guidewire Webhooks and Event Integrations

Overview

Wire Guidewire's event system into downstream consumers — analytics warehouses, fraud-detection services, broker-portal cache invalidators, customer-notification services. Guidewire emits App Events (typed business events fired on entity-state transitions); they are configured server-side in Gosu and routed to a destination (SQS, Kafka, or webhook URL). The consumer side has its own production failure modes that this skill addresses.

Five production failures this skill prevents:

1. Event registered nowhere — code subscribes to a claim.bound event that was never registered in Gosu; consumer waits forever; no error surfaces because there's nothing to error on.
2. Duplicate processing — the queue redelivers a message after consumer ack timeout; consumer creates a duplicate downstream record (duplicate notification, duplicate analytics row).
3. Out-of-order arrival — events for the same claim arrive in the wrong order (claim.reserve.changed before claim.created); consumer rejects the reserve event because the parent claim does not yet exist locally.
4. Quiet event loss — consumer was down for 30 minutes; events that fired during that window are gone; nobody notices until a downstream report is missing rows.
5. Back-pressure cascade — producer (Guidewire) emits faster than the consumer drains the queue; queue depth grows; eventually the destination's queue retention expires and events are dropped.

Prerequisites

• A working integration per guidewire-install-auth and guidewire-sdk-patterns
• Access to the InsuranceSuite config zone for editing Gosu / messaging-destination XML
• A destination ready to receive events (AWS SQS queue + dead-letter queue, an HTTPS webhook endpoint, or a Kafka topic)
• The consumer service has its own datastore for idempotency keys (Redis with TTL ≥ 7d works; a database table also works)

Instructions

Build the integration in this order. Each step targets one of the five production failures listed in Overview.

1. Register the App Event in Gosu

Events not registered do not fire. The registration lives in gw.api.messaging.MessageEvents (or carrier-customized equivalent) and pairs an event code with a Gosu callback that decides whether to emit, and what payload.

// modules/configuration/gsrc/com/acme/messaging/ClaimEventBuilder.gs
package com.acme.messaging

uses gw.api.messaging.MessageContext
uses entity.Claim

class ClaimEventBuilder {
  static function buildClaimStatusChangedEvent(ctx: MessageContext, claim: Claim): String {
    return new gw.api.web.json.JsonObject() {{
      put("eventTyp…