Update to Zuora Coding Agent

{
  "description": "Produce Credit Memos / Debit Memos migration strategy, code inventory, and phases",
  "included_files": [],
  "name": "zuora-is-migration-design",
  "skill_md_contents": "---\nname: zuora-is-migration-design\ndescription: Produce Credit Memos / Debit Memos migration strategy, code inventory, and phases\nargument-hint: [codebase path and migration context]\nallowed-tools: [Read, Write, Glob, Grep, Bash, Agent, AskUserQuestion, Skill, mcp__zuora-mcp__ask_zuora, mcp__zuora-mcp__query_objects, mcp__zuora-mcp__zuora_codegen, mcp__zuora-mcp__get_account_summary]\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 producing a Credit Memos / Debit Memos migration plan. This plan guides the migration from legacy invoice adjustments (InvoiceAdjustment, InvoiceItemAdjustment, CreditBalanceAdjustment) to the modern Credit Memo and Debit Memo APIs.\n\n## REQUIRED INPUT: Codebase Path\n\nResolve the codebase path before any analysis:\n\n1. If `$ARGUMENTS` contains `codebase=<path>`, use that path directly and inform the user:\n   > \"Analyzing codebase at: `<resolved-path>`\"\n\n2. If no path is provided, run `pwd` to get the current working directory, then ask:\n   > \"No codebase path was provided. I will use the current working directory:\n   > `<pwd-result>`\n   >\n   > Is this correct, or would you like to specify a different path? (press Enter to confirm, or type the path)\"\n\n   **STOP. Wait for the user to confirm or provide a path before continuing.**\n\nDo NOT proceed with any analysis until the path is confirmed.\n\n## Input\n\nThe user's migration context and codebase path: $ARGUMENTS\n\nExpected format: `codebase=/path/to/billing-client` or `codebase=/path/to/billing-client context:tenant is production with 500 accounts`\n\n## Tool routing\n\nUse local code search and bundled IS references for code inventory, legacy API detection, mapping tables, and migration-plan structure. Use `mcp__zuora-mcp__zuora_codegen` for API details and model requirements, `mcp__zuora-mcp__query_objects` / `mcp__zuora-mcp__get_account_summary` for tenant state, and `mcp__zuora-mcp__ask_zuora` only when a specific IS capability, prerequisite, or accounting-semantics question remains unresolved after those sources.\n\n## Workflow\n\n> **When unsure about any aspect of the migration analysis, do NOT guess — list the uncertain items and ask the user before proceeding.**\n\n\n### Step 1: Assess current state\n\nGather context about the tenant's current state:\n- Ask the user about their tenant: sandbox or production? How many accounts/subscriptions?\n- Call `mcp__zuora-mcp__ask_zuora` for unresolved IS capability or prerequisite questions; prefer checking the bundled IS references and codegen first when they are likely to have the answer.\n- If the tenant is connected, use `mcp__zuora-mcp__query_objects` to inspect:\n  - Account count and billing models in use\n  - Invoice volume and credit balance usage\n  - Payment application patterns\n  - Custom integrations that reference invoices\n\nUse `mcp__zuora-mcp__get_account_summary` on a few representative accounts to understand the current billing structure.\n\n### Step 2: Code inventory — identify legacy adjustment usage\n\nSearch the codebase (at the path provided) for usage of legacy adjustment APIs:\n- Use `Grep` to find references to: `InvoiceAdjustment`, `InvoiceItemAdjustment`, `CreditBalanceAdjustment`\n- Look for SOAP API calls, method names, or class references\n- Document:\n  - Which files/classes use each legacy adjustment type\n  - How many call sites exist\n  - Whether usage is in core business logic or isolated helper functions\n- Example findings to report: \"Found 12 references to InvoiceAdjustment in service layer; 3 references in integration tests\"\n\n#### Resolving intent vs. implementation conflicts\n\nWhen reading legacy code, **method names and existing comments are the source of truth for intent**. The implementation may have used a different or incorrect API due to legacy limitations.\n\nFor each legacy adjustment call site found:\n1. Read the method name, class name, and any existing comments/Javadoc first.\n2. Read the implementation second.\n3. If they conflict (e.g., method is named `writeOffInvoice` but the body uses `CreditBalanceAdjustment type=Decrease`, which is a credit-apply operation, not a write-off):\n   - **Do NOT guess which IS API to use.**\n   - **Do NOT infer intent from the implementation.**\n   - List the conflict explicitly and ask the user, for example:\n     > \"Method `writeOffInvoice` uses `CreditBalanceAdjustment type=Decrease` in its implementation,\n     > but a write-off and a credit-apply are different IS operations:\n     > - Write-off: `PUT /v1/invoices/{invoiceKey}/write-off`\n     > - Apply existing credit memo: `PUT /v1/credit-memos/{creditMemoKey}/apply`\n     >\n     > Which is the correct IS mapping for this method?\"\n4. **Do NOT rename or change method names or class names** during migration — they express business intent.\n\n### Step 3: Identify integration impacts\n\nAsk the user about:\n- Downstream systems that consume billing documents (ERP, tax engines, reporting)\n- Custom reports or exports that reference adjustments\n- Payment gateway integrations\n- Dunning and collections processes\n- Revenue recognition workflows\n\n### Step 3b: Data Warehouse Assessment\n\nUse `AskUserQuestion` to ask the following two questions **in a single call**:\n\n**Question 1:** \"Does your system include a Data Warehouse or BI reporting layer that reads Zuora data? (e.g., dbt models, Fivetran/HVR pipelines, Looker, raw SQL reports, Snowflake/BigQuery views)\"\n- Options: \"Yes — we have DW/BI queries that read Zuora tables\" / \"No — no DW layer to update\"\n\n**STOP. Wait for the answer before continuing.**\n\nIf the user answers **No**, skip the rest of Step 3b and proceed to Step 4.\n\nIf the user answers **Yes**, ask:\n\n**Question 2:** \"How does your DW pipeline sync Zuora data — incremental (only new/changed records each run) or full historical sync (full rebuild from scratch each run)?\"\n- Options: \"Incremental sync — we only process new/changed records\" / \"Full historical sync — we rebuild history on every run\" / \"Mixed — some models incremental, some full sync\"\n\nRecord the DW sync mode. Then ask the user to share their existing SQL queries or model files that read from the following legacy Zuora objects (one or more may apply):\n- `InvoicePayment` / `invoice_payment`\n- `RefundInvoicePayment` / `refund_invoice_payment`\n- `CreditBalanceAdjustment` / `credit_balance_adjustment`\n- `InvoiceAdjustment` / `invoice_adjustment` or `InvoiceItemAdjustment`\n\nTell the user: \"You can paste the SQL directly, provide file paths, or describe which tables your models use. I will produce IS-compatible rewrites in the build phase.\"\n\nDocument everything collected here in the plan's DW section (see Step 7).\n\n### Step 4: Read reference materials\n\nFirst, list all files under `${CLAUDE_PLUGIN_ROOT}/references/` to understand what is available. Then read every file that is relevant to Credit Memos, Debit Memos, Invoice Settlement, or the APIs being migrated — **including `is-migration-dw-patterns.md` when DW requirements were identified in Step 3b**. Do not hardcode file names — the contents of the references folder may change across versions.\n\n### Step 5: Check API requirements\n\nCall `mcp__zuora-mcp__zuora_codegen` with `get_api_details` to understand REST API requirements for credit memos and debit memos.\n\n### Step 7: Produce the migration plan\n\nDeliver a structured document with the codebase path prominently noted:\n\n**Executive summary**: What Credit Memos / Debit Memos migration is, why it matters, scope, and timeline\n\n**Codebase inventory**: \n- Path analyzed: [record the path]\n- Legacy adjustment API usage found:\n  - InvoiceAdjustment: [file references and counts]\n  - InvoiceItemAdjustment: [file references and counts]\n  - CreditBalanceAdjustment: [file references and counts]\n- Estimated effort: Based on code spread\n\n**Current state assessment**: Summary of tenant usage patterns, custom integrations, and downstream impacts\n\n**Migration phases**:\n1. **Assessment** — code inventory (done above), downstream impact analysis\n2. **Code refactoring** — update each legacy adjustment call to use REST Credit Memo API\n   - When adding or updating comments on refactored methods, always include:\n     - **Before:** what the legacy code did (e.g., `// Before: CreditBalanceAdjustment type=Decrease via SOAP`)\n     - **After:** what the IS code does (e.g., `// After: PUT /v1/invoices/{invoiceKey}/write-off`)\n   - Do NOT remove or overwrite existing comments — append the Before/After note below them.\n   - Do NOT rename method names or class names.\n3. **Integration updates** — update downstream systems to consume Credit Memo / Debit Memo objects\n4. **Validation** — verify behavior matches legacy semantics\n5. **Production rollout** — deploy updated code\n\n**Risk matrix**: For each risk — likelihood, impact, mitigation\n\n**Validation checklist**: Code review points, integration test scenarios, edge cases\n\n**Dependencies and prerequisites**: API version, Zuora SDK version, team skill with REST APIs\n\n**Data Warehouse section** *(include only when DW requirements were identified in Step 3b)*:\n- Sync mode: [incremental / full historical / mixed]\n- DW tooling: [dbt / Fivetran / raw SQL / other]\n- Affected models / queries:\n  - [model name]: reads [InvoicePayment / RefundInvoicePayment / CreditBalanceAdjustment / etc.] → IS equivalent: [PaymentApplication / RefundApplication / retain as-is / etc.]\n- Net-new models required (no legacy equivalent):\n  - `dim_transactions_creditmemo` — reads `CreditMemo` + `CreditMemoItem`\n  - `dim_transactions_debitmemo` — reads `DebitMemo` + `DebitMemoItem`\n- Pipeline readiness: confirm DW sync includes `payment_application`, `credit_memo`, `debit_memo`, `refund_application` tables\n- IS-compatible SQL rewrites will be generated in the build phase (reference: `is-migration-dw-patterns.md`)\n\n---\n\n## CONFIRMATION GATE\n\nAfter completing the plan:\n\n1. Present the full plan to the user\n2. Write the plan to **`plan.md`** in the codebase root (or current working directory)\n3. Use the `AskUserQuestion` tool to ask:\n\n   - question: \"Plan saved to `plan.md`. Do you want to proceed with implementation?\"\n   - options: \"Yes, run /zuora-is-migration-build\" and \"No, I'll review the plan first\"\n\n**STOP. Do NOT continue until the user answers.**\n\n4. If the user selects \"Yes, run /zuora-is-migration-build\", immediately invoke the `Skill` tool with `skill: \"zuora-coding-agent:zuora-is-migration-build\"`.\n5. If the user selects \"No\", stop and let the user know the plan is saved and they can run `/zuora-is-migration-build` manually when ready.\n"
}