Update to Zuora Coding Agent

{
  "description": "Generate Credit Memos / Debit Memos migration implementation artifacts based on the plan",
  "included_files": [],
  "name": "zuora-is-migration-build",
  "skill_md_contents": "---\nname: zuora-is-migration-build\ndescription: Generate Credit Memos / Debit Memos migration implementation artifacts based on the plan\nargument-hint: [migration plan reference or specific artifacts needed]\nallowed-tools: [Read, Write, Edit, Glob, Grep, Bash, Agent, mcp__zuora-mcp__zuora_codegen, mcp__zuora-mcp__ask_zuora, mcp__zuora-mcp__query_objects, mcp__zuora-mcp__get_account_summary, mcp__zuora-mcp__manage_billing_documents]\n---\n\nCodex-only path resolution: When an instruction refers to `${CLAUDE_PLUGIN_ROOT}`, treat it as the root of this installed plugin. In Codex, resolve that root as the ancestor directory containing `skills/`, `references/`, and `.codex-plugin/`.\n\n\nYou are generating implementation artifacts for a Credit Memos / Debit Memos migration. The user should have a migration plan (from `/zuora-is-migration-design` or their own).\n\n## REQUIRED INPUT: Codebase Path\n\n**BEFORE PROCEEDING WITH ANY STEPS, YOU MUST OBTAIN THE CODEBASE PATH FROM THE USER.**\n\nResolve the codebase path in this order:\n1. If `$ARGUMENTS` contains `codebase=<path>`, use that path directly.\n2. If a `plan.md` exists in the current working directory (written by `/zuora-is-migration-design`), extract the codebase path from it — **skip asking the user**.\n3. Otherwise, IMMEDIATELY ask:\n\n\"To implement the migration, I need the path to your billing/integration codebase so I can locate and update the legacy adjustment API calls. What is the full path? (e.g., `/Users/yourname/workspace/acme-billing-client`)\"\n\nDo NOT attempt to modify any code until you have this path. This is a blocker step.\n\n## Input\n\nThe user's request: $ARGUMENTS\n\nExpected format: `codebase=/path/to/billing-client [additional requirements]`\n\n## Tool routing\n\nUse local code search and file edits for migration implementation work. Use `mcp__zuora-mcp__zuora_codegen` for REST API classes, endpoint details, model fields, enum values, and SDK rules. Use account summary and billing document tools for verification. `mcp__zuora-mcp__ask_zuora` is allowed only as a fallback for a specific IS capability or accounting-semantics question that remains after references and codegen are checked. If business intent is unclear, ask the user to choose the intended mapping before changing code.\n\n## Workflow\n\n### Step 2: Review the migration plan\n\nUnderstand which code modifications are needed. Ask the user:\n- \"Do you have a migration plan from `/zuora-is-migration-design`? If so, share the key findings about which legacy APIs need to be updated.\"\n- If no plan exists, recommend running `/zuora-is-migration-design codebase=/path` first to inventory the code\n\n### Step 3: Identify and update legacy adjustment code\n\n**Key principle:** Modify existing methods to use Credit Memo APIs — do NOT create new methods.\n\n**Process:**\n1. Use `Grep` to find all SOAP calls to: `InvoiceAdjustment` / `InvoiceItemAdjustment` / `CreditBalanceAdjustment` in the codebase\n2. For each call site, locate the method that contains it\n3. Replace SOAP calls with REST CreditMemo API calls (using Zuora SDK)\n4. Update method body only; preserve method name and interface\n5. Example: Change `createInvoiceAdjustment()` body from SOAP to REST, but keep the same method signature\n\n**What NOT to do:**\n- Do NOT create `createCreditMemo()` as a new method alongside existing `createInvoiceAdjustment()`\n- Do NOT add new service classes like `CreditMemoRestService`\n- Modify existing code paths in-place, don't introduce parallel implementations\n- Do NOT rename or change existing method names — modify the implementation in-place, preserve the original signature\n- When unsure how to migrate a call, do NOT guess — list the uncertain items and ask the user before proceeding\n\n**Validation and reconciliation:**\n- Create validation scripts to verify Credit Memo behavior matches legacy semantics\n- Verify that bill run automatically generates CreditMemo for negative charges\n- Include pre/post migration comparison logic\n\n### Step 3: Implementation approach\n\n**Modify existing methods, do NOT introduce new ones:**\n- Update existing method bodies to use REST CreditMemo APIs instead of legacy SOAP\n- Keep the same method names, packages, and interfaces to avoid breaking changes\n- Example: `InvoiceAdjustmentService.createAdjustment()` changes from SOAP to REST internally, but external callers see no difference\n\n**Determine the correct API class before writing any code:**\n- Call `zuora_codegen list_api_classes` to find the relevant API class\n- Call `zuora_codegen get_class_apis` to list available methods in that class\n- Do NOT hardcode API class names\n- Follow the mandatory workflow: `code_guidance` → `get_api_details` → `get_model_details` → `code_rules`\n\n**Use Zuora SDK for REST calls:**\n- Use `com.zuora.model.*` classes for request/response objects\n- Use `com.zuora.api.CreditmemosApi` (or similar) from SDK\n- Initialize with basic auth using credentials from config\n- Do NOT implement manual HTTP calls or custom JSON parsing\n\n**Handle SOAP→REST transition:**\n- Replace SOAP service calls with REST equivalents in existing method implementations\n- Test that existing callers continue to work without code changes\n- Update integration tests to verify REST behavior\n\n**Code organization:**\n- Keep modified code in existing package structure\n- Test classes: Update existing test classes to verify behavior (do NOT create separate `*RestTest` classes)\n- **Important:** When renaming test classes, ensure file names match Java naming conventions (file name = public class name with `.java` extension)\n\n**When multiple IS APIs could apply — ask before coding**\n\nSome legacy operations (e.g., `CreditBalanceAdjustment`, `InvoiceItemAdjustment`) can be migrated to more than one IS API, each with a different business meaning. Do NOT pick silently. When you are unsure which IS API matches the business intent of the original code, ask the user.\n\nFor example, a method that reduces an invoice balance could map to:\n- `PUT /v1/creditmemos/{id}/apply` — if an existing Credit Memo is being applied\n- `PUT /v1/invoices/{invoiceKey}/write-off` — if a new write-off Credit Memo should be created and applied atomically\n\nThese have different accounting implications. Present the options and their business meanings to the user and wait for confirmation before writing any code.\n\nApply this principle any time you identify ambiguity, not just for write-off scenarios.\n\n### Step 5: Generate supporting artifacts\n\nWrite to files:\n- Migration scripts (in user's preferred language)\n- Validation scripts with expected vs actual comparisons\n- Runbook with step-by-step execution instructions\n- Code review checklist for API changes\n\n### Step 6: Data Warehouse SQL Rewrite\n\n**Run this step only when the migration plan (or the user) indicates DW requirements exist.**\n\nRead `${CLAUDE_PLUGIN_ROOT}/references/is-migration-dw-patterns.md` before generating any SQL.\n\n#### 6a — Collect customer SQL\n\nIf the user has not already provided their DW SQL/models, ask:\n\n\"Please share the SQL queries or model files that reference legacy Zuora settlement objects (`InvoicePayment`, `RefundInvoicePayment`, `CreditBalanceAdjustment`, `InvoiceAdjustment`, `InvoiceItemAdjustment`). You can paste the SQL directly, provide file paths, or point to your dbt project directory.\"\n\nAlso ask or confirm:\n- \"What DW tooling do you use? (e.g., dbt, Fivetran, raw SQL, Snowflake views, Looker PDT)\"\n- \"Confirmed sync mode: incremental or full historical?\" (should already be in the plan; re-confirm if unclear)\n\n**STOP. Wait for the answers before producing SQL.**\n\n#### 6b — Analyze the customer SQL\n\nFor each SQL file or query provided:\n1. Identify every legacy settlement object referenced: `InvoicePayment`, `RefundInvoicePayment`, `CreditBalanceAdjustment`, `InvoiceAdjustment`, `InvoiceItemAdjustment`\n2. Note table/view naming style (dbt `{{ ref() }}`, schema.table, view names, etc.)\n3. Note field names used — they may differ from dbt staging model convention\n4. Determine which IS object(s) replace each legacy reference (use the mapping table in `is-migration-dw-patterns.md`)\n\n#### 6c — Generate IS-compatible rewrites\n\nApply the correct pattern from `is-migration-dw-patterns.md` based on sync mode:\n\n**Incremental sync:**\n- Replace `InvoicePayment` CTEs with `PaymentApplication` (Pattern 1)\n- Replace `RefundInvoicePayment` CTEs with `RefundApplication` (Pattern 2)\n- Retain `CreditBalanceAdjustment`, `InvoiceAdjustment`, `InvoiceItemAdjustment` unchanged (historical pre-IS records)\n- Add net-new queries for `CreditMemo`/`CreditMemoItem` (Pattern 4) and `DebitMemo`/`DebitMemoItem` (Pattern 5)\n- Adapt table name style to match the customer's tooling (replace `stg_zuora__*` refs with their actual table names if not using dbt)\n\n**Full historical sync:**\n- Apply the UNION ALL + anti-join deduplication pattern for payments (Pattern 6) and refunds (Pattern 7)\n- Retain `CreditBalanceAdjustment` as-is — no IS equivalent (Pattern 8)\n- Add net-new queries for `CreditMemo` and `DebitMemo` (Patterns 4 and 5)\n\n**Mixed sync mode:**\n- Ask which models are incremental and which are full sync, then apply the appropriate pattern per model\n\n**Adapt to the customer's DW tooling:**\n- dbt: use `{{ ref('stg_zuora__<object>') }}` syntax, preserve model structure and CTE style\n- Fivetran / raw SQL: use `<schema>.<table>` notation matching their warehouse; omit dbt macros\n- If the customer uses a custom staging layer, substitute their actual table/view names wherever the patterns use `stg_zuora__*`\n- Preserve the customer's existing field aliases, column order, and SQL style — minimize diff size\n\n#### 6d — Handle net-new documents (CreditMemo / DebitMemo)\n\nCreditMemo and DebitMemo have no pre-IS equivalent — these are entirely additive. For each:\n1. Produce a new model/query based on Pattern 4 (CreditMemo) or Pattern 5 (DebitMemo)\n2. Adapt field names to match the customer's schema\n3. Confirm sign convention with the customer: CreditMemo items default to negative `transaction_amount`; DebitMemo items default to positive\n\n#### 6e — Output\n\nWrite each rewritten query to a file named `<original_filename>_is_rewrite.sql` (or update in-place if the user prefers). Include inline comments marking every IS change (use the `-- IS:` comment prefix convention from `is-migration-dw-patterns.md`).\n\nAt the end of this step, produce a summary table:\n\n| Original model | Legacy objects replaced | IS objects used | Sync pattern applied | New file |\n|---|---|---|---|---|\n| [model name] | InvoicePayment | PaymentApplication | Incremental | [filename] |\n| ... | | | | |\n\nAlso list any net-new models created for CreditMemo / DebitMemo.\n\n#### 6f — DW validation checklist\n\nOutput a checklist the customer can use before deploying:\n- [ ] Confirm DW pipeline syncs `payment_application`, `credit_memo`, `debit_memo`, `refund_application` tables\n- [ ] Validate staging model field names match customer's DW schema\n- [ ] Run IS-rewritten models against sandbox data\n- [ ] Compare output row counts and amounts against legacy models for overlapping historical period\n- [ ] Confirm no records are double-counted (run anti-join check: `COUNT(*)` on the union result vs each side separately)\n- [ ] Validate sign conventions on CreditMemo / DebitMemo amounts with AR/finance team\n- [ ] Enable new `CreditMemo` / `DebitMemo` objects in DW sync tool if not already present\n\n### Step 7: Read reference materials\n\nRead these references to ensure generated code follows established patterns:\n- `${CLAUDE_PLUGIN_ROOT}/references/is-migration-patterns.md` — phases, object mappings, API operations for Credit Memos / Debit Memos\n- `${CLAUDE_PLUGIN_ROOT}/references/is-migration-api-reference.md` — field-level mappings for legacy adjustments → Credit Memo objects\n- `${CLAUDE_PLUGIN_ROOT}/references/best-practices.md` — API integration standards\n- `${CLAUDE_PLUGIN_ROOT}/references/is-migration-dw-patterns.md` — DW object mapping, sync mode patterns, SQL examples, and pitfalls (read when DW requirements exist)\n\n### Step 8: Suggest validation\n\n- Run all scripts in sandbox first\n- Use `mcp__zuora-mcp__get_account_summary` to verify account state after Credit Memo conversion\n- Use `mcp__zuora-mcp__manage_billing_documents` to verify Credit Memo and Debit Memo generation\n- Run `/zuora-validate` on generated code\n- Verify REST services work correctly and legacy SOAP adjustment services are properly replaced/removed\n"
}