---
name: multi-asset-attribution-macro
description: >
  Runs Macro Attribution (Total Portfolio Attribution) to evaluate Plan Sponsor or CIO decisions.
  Decomposes total active return into Tactical Asset Allocation (TAA), Manager Selection,
  and Interaction effects. Accepts an xlsx file with policy and actual weights/returns,
  validates inputs, prompts for missing data, and generates a comprehensive attribution report.
metadata:
  display_name: "Macro Attribution (Multi-Asset)"
  short_description: "Decompose total fund active return into TAA, Selection, and Interaction effects."
  default_prompt: "Run macro attribution on my multi-asset portfolio."
  icon_path: "assets/icon.png"
---

# Macro Attribution (Multi-Asset) Skill

## Purpose

Decompose a total fund's active return versus its Strategic Asset Allocation (SAA) policy benchmark into three additive effects per asset class/manager sleeve:

| Effect | Formula | What it measures |
|---|---|---|
| **TAA (Allocation)** | `(w_act − w_pol) × (r_bench − R_pol_total)` | Impact of over/underweighting an asset class |
| **Selection** | `w_pol × (r_mgr − r_bench)` | Impact of manager out/underperformance |
| **Interaction** | `(w_act − w_pol) × (r_mgr − r_bench)` | Combined weight + return divergence |

---

## Invocation

```
/multi-asset-attribution-macro <user request>
```

Examples:
- `/multi-asset-attribution-macro Here is my fund's macro input xlsx`
- `/multi-asset-attribution-macro Run macro attribution on the uploaded file`

---

## Input Schema

The skill accepts input in **two forms**:

### Form 1 — Spec-compliant xlsx (preferred)

An Excel file containing a sheet named **Macro_Input** with the following columns:
- `period_id` (e.g., "2026-Q1")
- `asset_class` (e.g., "US Equity")
- `manager_name` (e.g., "Alpha Partners")
- `policy_weight` (Decimal, sums to 1.0)
- `actual_weight` (Decimal, sums to 1.0)
- `manager_return` (Decimal)
- `benchmark_return` (Decimal)

### Form 2 — Natural language + prompted collection

If no file is provided, the skill prompts for the required data.

---

## Step-by-Step Workflow

The skill MUST execute these steps in order:

### Step 1 — Detect input form

1. Check whether the user uploaded an xlsx file.
2. Otherwise, enter **prompted collection mode**.

### Step 2 — Validate inputs (`scripts/validate_inputs.py`)

Run the validator against the detected input. The validator checks:
- `policy_weight` sums to 1.0 ± 1e-4
- `actual_weight` sums to 1.0 ± 1e-4
- Required columns exist in the `Macro_Input` sheet.

If validation **passes** → proceed to Step 3.
If validation **fails** → display a clear error table and prompt the user to fix it.

### Step 3 — Run attribution (`scripts/run_attribution.py`)

1. Instantiate `MultiAssetMacroAttribution` from `MultiAssetMacroAttribution.py`
2. Call `calculate_effects()`
3. Generate `macro_attribution_report.xlsx`

### Step 4 — Deliver results

Present a structured summary of the Total Fund Effects and attach `macro_attribution_report.xlsx`.

---

## Prompt Rules (Prompted Collection Mode)

When inputs are missing or incomplete, prompt for them:

> "I need the fund data to run the Macro Attribution. Please provide an Excel file with a sheet named **Macro_Input** containing the following columns:
> `period_id`, `asset_class`, `manager_name`, `policy_weight`, `actual_weight`, `manager_return`, and `benchmark_return`.
> Note: Both policy weights and actual weights must sum to 100% (1.0)."

---

## Files in This Skill Package

```
multi-asset-attribution-macro/
├── SKILL.md                        ← This file
├── assets/
│   └── icon.png                    ← Skill icon
└── scripts/
    ├── validate_inputs.py          ← Input validator
    ├── run_attribution.py          ← Attribution runner
    └── MultiAssetMacroAttribution.py ← Core engine
```