Wealth Advisory API Planning
Workflow
- Read the task prompt,
input/payloads/request_memo.md, and input/payloads/answer_template.json.
- Extract
client_id, engagement type, planning horizon if supplied, and the required output fields. Set task_id from the current task directory name unless the harness provides it directly.
- Use
API_BASE if set; otherwise read the local environment access note for the base URL. Fetch only documented GET endpoints. Never call a judge endpoint.
- Fetch:
/api/clients/{client_id}
/api/source-documents?client_id={client_id}
/api/retirement-accounts?client_id={client_id}
/api/life-insurance?client_id={client_id}
/api/trust-candidates?client_id={client_id}
/api/policies/tax
/api/rmd-factors
- Compute every requested field from the API records and policy constants. Return only one JSON object, with JSON numbers for amounts and booleans as booleans.
Round USD outputs to cents at final assignment. For savings/differences, subtract unrounded values first, then round the result.
Source Resolution
Use source-specific controls instead of blindly taking the newest record.
- Household profile facts: prefer
SIGNED_PROFILE for age, planning year, filing status, marital status, annual non-IRA income, marginal tax rate, beneficiary count, liquid assets, estate value, and client goals.
- Retirement account facts: use the
CUSTODIAN_EXPORT account record for traditional balance, Roth balance, expected return, RMD start age, and recommended conversion years.
- ILIT policy facts: use the life-insurance endpoint for premium, death benefit, planned contribution date, owner, and transfer flag. If the output asks for a policy source and the policy record has no source type, use
SIGNED_PROFILE when signed household facts control implementation assumptions; otherwise use the most specific attorney/policy source present.
- Trust transfer asset facts: use the trust-candidate endpoint for asset value, growth, term, annuity, and payout inputs. If the output asks for the controlling trust asset source and the endpoint has no source type, use
ATTORNEY_MEMO for attorney-led trust/asset candidates.
- Goals and beneficiaries: prefer
SIGNED_PROFILE; use attorney or CRM facts only when signed facts are absent.
Populate source_resolution with the source type that controlled that category, not the endpoint name.
Estate Context
For trust and estate-liquidity outputs:
planning_year: controlling profile planning year.
exemption_used: policy estate-tax exemption for the planning year, doubled for married/MFJ households and single for single filers.
taxable_estate = max(estate_value - exemption_used, 0).
estate_tax_exposure = taxable_estate * estate_tax_rate.
liquid_assets_available: controlling liquid assets.
liquidity_gap_before_planning = max(estate_tax_exposure - liquid_assets_available, 0).
Include these context fields when the estate-context object is part of the observed task pattern, even if the template lists only a subset.
Roth Conversion And RMD
Use this for analysis_type: roth_conversion_rmd.
Inputs:
- Profile: planning year, age, filing status, annual non-IRA income, marginal tax rate, liquid assets.
- Policy: conversion bracket target for the filing status.
- Account: traditional balance, Roth balance, expected return, RMD start age, recommended conversion years.
- Memo/template: horizon year.
Conversion plan:
annual_conversion_amount = max(bracket_target - annual_non_ira_income, 0), capped only if total planned conversions would exceed the remaining traditional balance.
first_conversion_year = planning_year when the annual amount is positive.
conversion_years = recommended_conversion_years.
conversion_years_positive is the count of planned years with a positive conversion amount.
total_converted = annual_conversion_amount * conversion_years_positive, capped by available traditional balance.
total_conversion_tax = total_converted * marginal_tax_rate.
RMD simulation through the horizon is year-inclusive. Maintain separate baseline and conversion paths.
For each year from planning_year through horizon_year:
- Compute current age as
age + (year - planning_year).
- In the conversion path only, before any RMD, convert the planned annual amount while the year is within the planned conversion window and traditional balance remains.
- If current age is at least the RMD start age, compute
rmd = traditional_balance / rmd_factor[current_age], add rmd * marginal_tax_rate to that path's RMD tax, and subtract the RMD from traditional balance.
- Grow ending traditional and Roth balances by
1 + expected_return.
Outputs:
first_rmd_year = planning_year + max(rmd_start_age - age, 0).
baseline_rmd_tax_through_horizon: baseline accumulated RMD tax.
conversion_rmd_tax_through_horizon: conversion-path accumulated RMD tax, excluding conversion tax.
rmd_tax_savings_through_horizon: baseline RMD tax minus conversion-path RMD tax.
- Horizon legacy balances come from the conversion path after the horizon year's growth.
heir_tax_profile: use MIXED_TAXABLE_AND_TAX_FREE when both Roth and traditional balances remain material, MOSTLY_TAX_FREE when the horizon balance is predominantly Roth, and MOSTLY_TAXABLE when little or no Roth balance remains.
Recommendation:
- Choose
STAGED_ROTH_CONVERSION and SUITABLE when bracket headroom is positive, conversion tax is supportable from liquid assets, and RMD tax savings are positive.
- Use
LIQUIDITY_CONSTRAINT when projected conversion taxes cannot be paid from available liquid assets.
- Use
RMD_NEAR_TERM only when near-term RMD timing is the dominant reason to defer or reduce the plan; otherwise use TAX_BRACKET_MANAGEMENT for suitable staged conversions.
- Use
DEFER/NO_CONVERSION when there is no bracket headroom or the simulation does not support conversion.
ILIT Crummey Implementation
Use this for analysis_type: ilit_crummey_implementation and for ILIT sections in combined estate plans.
Inputs:
- Planning year and beneficiary count from the controlling profile.
- Annual gift exclusion and estate tax rate from policy constants.
- Policy death benefit, premium, contribution date, and existing-transfer flag from life insurance.
Gift and administration calculations:
annual_exclusion_per_beneficiary is the policy annual exclusion for the planning year.
annual_exclusion_capacity = annual_exclusion_per_beneficiary * beneficiary_count.
premium_gap = max(annual_premium - annual_exclusion_capacity, 0).
notices_required = beneficiary_count.
notice_due_date = contribution_date + 7 calendar days.
withdrawal_window_end = notice_due_date + 30 calendar days.
earliest_premium_payment_date = withdrawal_window_end + 1 calendar day.
dedicated_bank_account_required = true for ILIT funding cycles.
Risk flag:
- No premium gap and no existing policy transfer:
LOW_IF_FORMALITIES_MET.
- Premium gap only:
EXCLUSION_SHORTFALL.
- Existing policy transfer only:
THREE_YEAR_LOOKBACK.
- Both issues:
THREE_YEAR_LOOKBACK_AND_EXCLUSION_SHORTFALL.
Recommendation mapping:
- Low risk:
FUND_WITH_CRUMMEY_NOTICES, SUITABLE_WITH_ADMINISTRATION.
- Premium gap only:
USE_LIFETIME_EXEMPTION_FOR_SHORTFALL, usually BORDERLINE.
- Existing transfer only:
USE_NEW_POLICY_OR_ACCEPT_LOOKBACK, usually BORDERLINE.
- Both issues:
DISCLOSE_LOOKBACK_AND_USE_EXEMPTION, usually NOT_SUITABLE or BORDERLINE depending on template choices and facts.
Estate result:
estate_inclusion_risk equals the risk flag.
projected_outside_estate_if_implemented is the death benefit when the ILIT is implemented, with the risk flag disclosing inclusion concerns.
tax_liquidity_support = death_benefit * estate_tax_rate.
GRAT Versus CRAT
Use this for analysis_type: trust_comparison and trust-transfer sections in combined estate plans.
Inputs:
- Client goals from the controlling profile: rank
low < moderate < high for family transfer priority and philanthropic intent.
- Estate context as above.
- Trust candidate asset value, growth rate, GRAT term, GRAT annuity rate, CRAT term, and CRAT payout rate.
- Policy estate tax rate and charitable deduction rate.
GRAT:
projected_remainder_to_heirs = asset_value * (1 + expected_growth_rate) ^ grat_term_years - asset_value * grat_annuity_rate * grat_term_years.
estimated_estate_tax_reduction = projected_remainder_to_heirs * estate_tax_rate.
mortality_inclusion_risk = TERM_SURVIVAL_REQUIRED.
CRAT:
projected_charitable_remainder = asset_value * (1 + expected_growth_rate) ^ crat_term_years - asset_value * crat_payout_rate * crat_term_years.
estimated_income_tax_deduction = projected_charitable_remainder * charitable_deduction_rate.
family_transfer_fit is LOW when family transfer priority dominates philanthropy, HIGH when philanthropy dominates, and MODERATE when the goals are balanced.
Recommendation:
- Prefer
GRAT when family transfer priority is at least as strong as philanthropic intent; use CHILDREN_TRANSFER_PRIORITY and set CRAT as SECONDARY_CHARITABLE_TOOL.
- Prefer
CRAT when philanthropic intent clearly dominates; use PHILANTHROPIC_PRIORITY and set GRAT as SECONDARY_FAMILY_TRANSFER_TOOL.
Estate Liquidity Action Plan
Use this for analysis_type: estate_liquidity_action_plan.
Combine the estate context, ILIT, and GRAT/CRAT calculations.
Recommendation:
- Use
COMBINE_ILIT_AND_GRAT when the ILIT is administratively workable and GRAT is the preferred trust strategy.
- Use
CRAT_WITH_LIQUIDITY_REVIEW when CRAT is preferred because philanthropic intent dominates.
- Use
ILIT_WITH_EXEMPTION_REVIEW when ILIT premium gaps, transfer lookback, or exemption allocation issues dominate the plan.
Sequencing:
ILIT_FIRST_THEN_GRAT for workable ILIT plus GRAT strategy.
TRUST_DECISION_FIRST when CRAT or trust selection must be resolved before implementation.
ILIT_FIRST_THEN_ATTORNEY_REVIEW when ILIT formalities or exemption issues need attorney review before broader execution.
Action set:
- Always sort alphabetically.
- Include
ATTORNEY_DRAFT_REVIEW for attorney-coordinated estate liquidity plans.
- Include
ILIT_CRUMMEY_NOTICE_CYCLE when an ILIT premium cycle is part of the plan.
- Include
LIFETIME_EXEMPTION_ALLOCATION when premium gaps or exemption use must be addressed.
- Include
GRAT_FOR_APPRECIATING_SHARES when GRAT is preferred.
- Include
CRAT_FOR_CHARITABLE_REMAINDER when CRAT is preferred.
Final JSON Checks
- Include every required top-level key from the template.
- Use only enum values allowed by the template.
- Keep
action_set alphabetically sorted.
- Use ISO
YYYY-MM-DD dates.
- Do not include explanatory prose, Markdown, citations, or code fences outside the JSON.
1---2name: wealth-advisory-api-planning3description: Solve private wealth advisory task-group API planning outputs as schema-conforming JSON. Use when Codex must read a local prompt, request memo, and answer_template.json, fetch advisory records from the provided API, resolve conflicting client/source data, and compute Roth conversion/RMD, ILIT Crummey, GRAT/CRAT, or estate-liquidity action-plan fields.4metadata:5 source: https://skillmd.com/skills/prism-shadow/wealth-advisory-api-planning6---78# Wealth Advisory API Planning910## Workflow11121. Read the task prompt, `input/payloads/request_memo.md`, and `input/payloads/answer_template.json`.132. Extract `client_id`, engagement type, planning horizon if supplied, and the required output fields. Set `task_id` from the current task directory name unless the harness provides it directly.143. Use `API_BASE` if set; otherwise read the local environment access note for the base URL. Fetch only documented GET endpoints. Never call a judge endpoint.154. Fetch:16 - `/api/clients/{client_id}`17 - `/api/source-documents?client_id={client_id}`18 - `/api/retirement-accounts?client_id={client_id}`19 - `/api/life-insurance?client_id={client_id}`20 - `/api/trust-candidates?client_id={client_id}`21 - `/api/policies/tax`22 - `/api/rmd-factors`235. Compute every requested field from the API records and policy constants. Return only one JSON object, with JSON numbers for amounts and booleans as booleans.2425Round USD outputs to cents at final assignment. For savings/differences, subtract unrounded values first, then round the result.2627## Source Resolution2829Use source-specific controls instead of blindly taking the newest record.3031- Household profile facts: prefer `SIGNED_PROFILE` for age, planning year, filing status, marital status, annual non-IRA income, marginal tax rate, beneficiary count, liquid assets, estate value, and client goals.32- Retirement account facts: use the `CUSTODIAN_EXPORT` account record for traditional balance, Roth balance, expected return, RMD start age, and recommended conversion years.33- ILIT policy facts: use the life-insurance endpoint for premium, death benefit, planned contribution date, owner, and transfer flag. If the output asks for a policy source and the policy record has no source type, use `SIGNED_PROFILE` when signed household facts control implementation assumptions; otherwise use the most specific attorney/policy source present.34- Trust transfer asset facts: use the trust-candidate endpoint for asset value, growth, term, annuity, and payout inputs. If the output asks for the controlling trust asset source and the endpoint has no source type, use `ATTORNEY_MEMO` for attorney-led trust/asset candidates.35- Goals and beneficiaries: prefer `SIGNED_PROFILE`; use attorney or CRM facts only when signed facts are absent.3637Populate `source_resolution` with the source type that controlled that category, not the endpoint name.3839## Estate Context4041For trust and estate-liquidity outputs:4243- `planning_year`: controlling profile planning year.44- `exemption_used`: policy estate-tax exemption for the planning year, doubled for married/MFJ households and single for single filers.45- `taxable_estate = max(estate_value - exemption_used, 0)`.46- `estate_tax_exposure = taxable_estate * estate_tax_rate`.47- `liquid_assets_available`: controlling liquid assets.48- `liquidity_gap_before_planning = max(estate_tax_exposure - liquid_assets_available, 0)`.4950Include these context fields when the estate-context object is part of the observed task pattern, even if the template lists only a subset.5152## Roth Conversion And RMD5354Use this for `analysis_type: roth_conversion_rmd`.5556Inputs:5758- Profile: planning year, age, filing status, annual non-IRA income, marginal tax rate, liquid assets.59- Policy: conversion bracket target for the filing status.60- Account: traditional balance, Roth balance, expected return, RMD start age, recommended conversion years.61- Memo/template: horizon year.6263Conversion plan:6465- `annual_conversion_amount = max(bracket_target - annual_non_ira_income, 0)`, capped only if total planned conversions would exceed the remaining traditional balance.66- `first_conversion_year = planning_year` when the annual amount is positive.67- `conversion_years = recommended_conversion_years`.68- `conversion_years_positive` is the count of planned years with a positive conversion amount.69- `total_converted = annual_conversion_amount * conversion_years_positive`, capped by available traditional balance.70- `total_conversion_tax = total_converted * marginal_tax_rate`.7172RMD simulation through the horizon is year-inclusive. Maintain separate baseline and conversion paths.7374For each year from `planning_year` through `horizon_year`:75761. Compute current age as `age + (year - planning_year)`.772. In the conversion path only, before any RMD, convert the planned annual amount while the year is within the planned conversion window and traditional balance remains.783. If current age is at least the RMD start age, compute `rmd = traditional_balance / rmd_factor[current_age]`, add `rmd * marginal_tax_rate` to that path's RMD tax, and subtract the RMD from traditional balance.794. Grow ending traditional and Roth balances by `1 + expected_return`.8081Outputs:8283- `first_rmd_year = planning_year + max(rmd_start_age - age, 0)`.84- `baseline_rmd_tax_through_horizon`: baseline accumulated RMD tax.85- `conversion_rmd_tax_through_horizon`: conversion-path accumulated RMD tax, excluding conversion tax.86- `rmd_tax_savings_through_horizon`: baseline RMD tax minus conversion-path RMD tax.87- Horizon legacy balances come from the conversion path after the horizon year's growth.88- `heir_tax_profile`: use `MIXED_TAXABLE_AND_TAX_FREE` when both Roth and traditional balances remain material, `MOSTLY_TAX_FREE` when the horizon balance is predominantly Roth, and `MOSTLY_TAXABLE` when little or no Roth balance remains.8990Recommendation:9192- Choose `STAGED_ROTH_CONVERSION` and `SUITABLE` when bracket headroom is positive, conversion tax is supportable from liquid assets, and RMD tax savings are positive.93- Use `LIQUIDITY_CONSTRAINT` when projected conversion taxes cannot be paid from available liquid assets.94- Use `RMD_NEAR_TERM` only when near-term RMD timing is the dominant reason to defer or reduce the plan; otherwise use `TAX_BRACKET_MANAGEMENT` for suitable staged conversions.95- Use `DEFER`/`NO_CONVERSION` when there is no bracket headroom or the simulation does not support conversion.9697## ILIT Crummey Implementation9899Use this for `analysis_type: ilit_crummey_implementation` and for ILIT sections in combined estate plans.100101Inputs:102103- Planning year and beneficiary count from the controlling profile.104- Annual gift exclusion and estate tax rate from policy constants.105- Policy death benefit, premium, contribution date, and existing-transfer flag from life insurance.106107Gift and administration calculations:108109- `annual_exclusion_per_beneficiary` is the policy annual exclusion for the planning year.110- `annual_exclusion_capacity = annual_exclusion_per_beneficiary * beneficiary_count`.111- `premium_gap = max(annual_premium - annual_exclusion_capacity, 0)`.112- `notices_required = beneficiary_count`.113- `notice_due_date = contribution_date + 7 calendar days`.114- `withdrawal_window_end = notice_due_date + 30 calendar days`.115- `earliest_premium_payment_date = withdrawal_window_end + 1 calendar day`.116- `dedicated_bank_account_required = true` for ILIT funding cycles.117118Risk flag:119120- No premium gap and no existing policy transfer: `LOW_IF_FORMALITIES_MET`.121- Premium gap only: `EXCLUSION_SHORTFALL`.122- Existing policy transfer only: `THREE_YEAR_LOOKBACK`.123- Both issues: `THREE_YEAR_LOOKBACK_AND_EXCLUSION_SHORTFALL`.124125Recommendation mapping:126127- Low risk: `FUND_WITH_CRUMMEY_NOTICES`, `SUITABLE_WITH_ADMINISTRATION`.128- Premium gap only: `USE_LIFETIME_EXEMPTION_FOR_SHORTFALL`, usually `BORDERLINE`.129- Existing transfer only: `USE_NEW_POLICY_OR_ACCEPT_LOOKBACK`, usually `BORDERLINE`.130- Both issues: `DISCLOSE_LOOKBACK_AND_USE_EXEMPTION`, usually `NOT_SUITABLE` or `BORDERLINE` depending on template choices and facts.131132Estate result:133134- `estate_inclusion_risk` equals the risk flag.135- `projected_outside_estate_if_implemented` is the death benefit when the ILIT is implemented, with the risk flag disclosing inclusion concerns.136- `tax_liquidity_support = death_benefit * estate_tax_rate`.137138## GRAT Versus CRAT139140Use this for `analysis_type: trust_comparison` and trust-transfer sections in combined estate plans.141142Inputs:143144- Client goals from the controlling profile: rank `low < moderate < high` for family transfer priority and philanthropic intent.145- Estate context as above.146- Trust candidate asset value, growth rate, GRAT term, GRAT annuity rate, CRAT term, and CRAT payout rate.147- Policy estate tax rate and charitable deduction rate.148149GRAT:150151- `projected_remainder_to_heirs = asset_value * (1 + expected_growth_rate) ^ grat_term_years - asset_value * grat_annuity_rate * grat_term_years`.152- `estimated_estate_tax_reduction = projected_remainder_to_heirs * estate_tax_rate`.153- `mortality_inclusion_risk = TERM_SURVIVAL_REQUIRED`.154155CRAT:156157- `projected_charitable_remainder = asset_value * (1 + expected_growth_rate) ^ crat_term_years - asset_value * crat_payout_rate * crat_term_years`.158- `estimated_income_tax_deduction = projected_charitable_remainder * charitable_deduction_rate`.159- `family_transfer_fit` is `LOW` when family transfer priority dominates philanthropy, `HIGH` when philanthropy dominates, and `MODERATE` when the goals are balanced.160161Recommendation:162163- Prefer `GRAT` when family transfer priority is at least as strong as philanthropic intent; use `CHILDREN_TRANSFER_PRIORITY` and set CRAT as `SECONDARY_CHARITABLE_TOOL`.164- Prefer `CRAT` when philanthropic intent clearly dominates; use `PHILANTHROPIC_PRIORITY` and set GRAT as `SECONDARY_FAMILY_TRANSFER_TOOL`.165166## Estate Liquidity Action Plan167168Use this for `analysis_type: estate_liquidity_action_plan`.169170Combine the estate context, ILIT, and GRAT/CRAT calculations.171172Recommendation:173174- Use `COMBINE_ILIT_AND_GRAT` when the ILIT is administratively workable and GRAT is the preferred trust strategy.175- Use `CRAT_WITH_LIQUIDITY_REVIEW` when CRAT is preferred because philanthropic intent dominates.176- Use `ILIT_WITH_EXEMPTION_REVIEW` when ILIT premium gaps, transfer lookback, or exemption allocation issues dominate the plan.177178Sequencing:179180- `ILIT_FIRST_THEN_GRAT` for workable ILIT plus GRAT strategy.181- `TRUST_DECISION_FIRST` when CRAT or trust selection must be resolved before implementation.182- `ILIT_FIRST_THEN_ATTORNEY_REVIEW` when ILIT formalities or exemption issues need attorney review before broader execution.183184Action set:185186- Always sort alphabetically.187- Include `ATTORNEY_DRAFT_REVIEW` for attorney-coordinated estate liquidity plans.188- Include `ILIT_CRUMMEY_NOTICE_CYCLE` when an ILIT premium cycle is part of the plan.189- Include `LIFETIME_EXEMPTION_ALLOCATION` when premium gaps or exemption use must be addressed.190- Include `GRAT_FOR_APPRECIATING_SHARES` when GRAT is preferred.191- Include `CRAT_FOR_CHARITABLE_REMAINDER` when CRAT is preferred.192193## Final JSON Checks194195- Include every required top-level key from the template.196- Use only enum values allowed by the template.197- Keep `action_set` alphabetically sorted.198- Use ISO `YYYY-MM-DD` dates.199- Do not include explanatory prose, Markdown, citations, or code fences outside the JSON.