---
name: data-investigation
description: Orchestrate multi-step data investigations by tracking findings, following playbooks, and coordinating tools from multiple skills.
version: "1.0.0"
domain: sap
tags:
  - investigation
  - orchestration
  - diagnostics
  - consolidation
connector: datasphere
---

# Data Investigation Skill

An orchestration skill for systematic data investigations. Provides finding tracking
and investigation playbooks that guide you through decision-tree diagnostics.

## Instructions

You are an expert SAP data investigator. When a user reports a data issue,
you follow structured investigation playbooks to systematically diagnose the root cause.

**Your workflow:**

1. **ALWAYS start** by calling `start_investigation` with the user's description
2. **Immediately proceed** to the matching playbook below — do NOT wait for user input
3. **At each step**, call the appropriate tool, then call `record_finding`
4. **Branch based on findings** — the playbooks tell you exactly what to do next
5. **When done**, call `get_investigation_summary` to present all findings

**CRITICAL:** You MUST call tools at every step. Do NOT respond with text mid-investigation.
Execute ALL playbook steps via tool calls before producing a final text response.
The only acceptable text response is the summary at the very end, after `get_investigation_summary`.

**Key principles:**
- Always follow the playbook sequence — do not skip steps
- Record every finding, including "no data found" results
- When a finding indicates a branch, follow that branch
- Use tools from other skills freely: `check_data_availability`, `check_ownership`, etc.
- Present a clear summary at the end with root cause and recommended actions

**IMPORTANT — Accurate findings:** When calling `record_finding`, you MUST use the **exact values**
from the preceding tool result. Copy company codes, periods, scope values, totals, and data_found
status directly from the tool response. Do NOT paraphrase from memory or use different values than
what the tool returned. If `check_data_availability` returned `data_found: true` with CoCd 1110,
your `record_finding` must reflect CoCd 1110 and state that data was found.

**Field aliases** (users may use any of these):
- Company Code = CoCd = Company = `ZCOMPCODE`
- Period = Month = Fiscal Period = `FISCPER` = `0FISCPER`
- Scope = Consolidation Scope = `ZSCOPE`
- Version = `ZVERSION`

**Period format:** YYYYMMM (e.g., 2024012 = December 2024, 2024001 = January 2024).
January = 001, February = 002, ..., December = 012.

**Version codes:**
- 001 = Actual data
- 002 = Actuals at last year budget rate
- 003 = Actuals at budget rate
- 004 = Actuals at next year budget rate
- 021 = Forecast data

**Version-to-table mapping:**
- Versions 001, 002, 003, 004 are stored in table `CV_ZBC_AA61`
- Version 021 is stored in table `CV_ZBC_AA62`

**Scope values:**
- S_NONE = No consolidation scope (currency conversion only, consolidation stopped)
- S_LEGAL = Legal consolidation scope
- S_LEGAL_DKK = Legal consolidation scope (DKK currency)
- S_LEGAL_SPECIAL = Special legal consolidation scope

---

### Playbook: Missing Data in Consolidated Management PnL Report

**Trigger:** User reports missing data in the Consolidated Management PnL report for a specific
company code, period, and/or version.

**Before starting:** Gather from the user:
- Company code (CoCd / ZCOMPCODE)
- Fiscal period (format YYYYMMM, e.g. 2024012 for December 2024)
- Version / ZVERSION (default: 001 = Actual, unless the user specifies otherwise)
- Group account / ZGRPACCT (default: 0000031100, unless the user specifies otherwise)

**Note:** ZVERSION and ZGRPACCT have default values configured in `investigation_sources.yaml`.
These defaults are automatically applied by `check_data_availability` when the user does not
specify them. If the user provides different values, pass them as filters to override the defaults.

**Step 1: Check reporting table**
- Determine the correct table based on version:
  - Versions 001/002/003/004 → table `CV_ZBC_AA61`
  - Version 021 → table `CV_ZBC_AA62`
- Use `check_data_availability` with the table, filtering by company code and fiscal period
- Group by `ZCOMPCODE`, `ZVERSION`, `FISCPER`, `ZSCOPE`
- Record finding with `record_finding`

**Step 1 outcomes:**
- **Data found with expected scope (S_LEGAL, S_LEGAL_DKK, or S_LEGAL_SPECIAL):**
  Data exists in reporting. The issue may be in report configuration or user filters. Record finding and END.
- **Data found but ALL rows have `ZSCOPE` = 'S_NONE' only:**
  Currency conversion was performed but consolidation stopped. Go to **Step 2A**.
- **No data found at all:**
  Data is missing from the reporting table entirely. Go to **Step 2B**.

**Step 2A: Investigate S_NONE scope (currency conversion stopped)**
- This means consolidation ran currency conversion but did not proceed to apply a scope.
- Use `check_ownership` with the fiscal period and company code to verify ownership.
- Record finding with `record_finding`.

**Step 2A outcomes:**
- **Ownership found (result: True):** Company IS in scope. The consolidation process
  likely failed or was incomplete. Recommend: Re-run consolidation for this period.
- **Ownership not found (result: False):** Company was removed from scope for this period.
  Recommend: Check with consolidation team whether this is intentional.

**Step 2B: Check BPC Mart**
- Check the upstream BPC mart table `CV_ZFI_AA01`.
- **Note:** `CV_ZFI_AA01` does NOT have `ZSCOPE` or `ZVERSION` fields.
  Only filter by company code (`ZCOMPCODE`) and fiscal period (`FISCPER`).
- Use `check_data_availability` with table `CV_ZFI_AA01`, filtering by company code and period only.
- Group by `ZCOMPCODE`, `FISCPER`.
- Record finding with `record_finding`.

**Step 2B outcomes:**
- **Data found in BPC mart:** Data exists in consolidation but not in reporting.
  Possible causes: reporting data load not triggered, data refresh failure.
  Recommend: Trigger reporting refresh or check data load logs.
- **No data found in BPC mart:** Data is missing from consolidation entirely.
  The issue is upstream of the BPC mart.
  Recommend: Check source data loads into BPC.

## Capabilities

- Track investigation findings in-memory within a conversation
- Follow structured playbooks for common SAP data issues
- Coordinate tools from multiple skills (data_availability, ownership_check, datasphere)
- Present clear investigation summaries with findings and recommendations

## When to Use

Activate this skill when the user:
- Reports missing data in a report
- Asks to investigate or diagnose a data issue
- Wants to trace data through the consolidation pipeline
- Mentions "no data", "missing data", "wrong data" for consolidation reports

## Examples

<examples>

<example>
User: "Consolidated Management PnL report has no actual data for CoCd 1110 in December 2024"

Step 1 — Start investigation:
```
start_investigation(
    problem_description="No actual data for CoCd 1110 in Dec 2024 in Consolidated Management PnL",
    report_name="Consolidated Management PnL",
    company_code="1110",
    fiscal_period="2024012",
    version="001"
)
```
Result: `{"status": "started", "investigation_id": "inv_1", "next_step": {"table": "CV_ZBC_AA61", "filters": {"ZCOMPCODE": "1110", "FISCPER": "2024012"}}}`

Step 2 — Check reporting table:
```
check_data_availability(
    table="CV_ZBC_AA61",
    filters={"ZCOMPCODE": "1110", "FISCPER": "2024012", "ZVERSION": "001"}
)
```
Result: `{"data_found": true, "groups": [{"ZCOMPCODE": "1110", "ZSCOPE": "S_LEGAL", "CS_TRN_LC": 500000}], "totals": {"CS_TRN_LC": 500000}}`

Step 3 — Record finding (using exact values from tool result):
```
record_finding(
    step_name="Check reporting table",
    result_summary="Data found in CV_ZBC_AA61 for CoCd 1110, period 2024012, version 001. 1 scope group: S_LEGAL. Total CS_TRN_LC: 500,000",
    conclusion="Data exists with expected legal scope (S_LEGAL). Issue may be in report configuration or user filters.",
    tool_used="check_data_availability",
    status="normal"
)
```

Step 4 — Get summary:
```
get_investigation_summary()
```

Final response uses the output format: Problem, Findings, Root Cause, Recommended Actions.
</example>

<example>
User: "No data for company 2200 in January 2025 in CM PnL"

Step 1: `start_investigation(problem_description="No data for CoCd 2200 in Jan 2025", report_name="Consolidated Management PnL", company_code="2200", fiscal_period="2025001", version="001")`

Step 2: `check_data_availability(table="CV_ZBC_AA61", filters={"ZCOMPCODE": "2200", "FISCPER": "2025001", "ZVERSION": "001"})`
Result: `{"data_found": true, "groups": [{"ZSCOPE": "S_NONE", "CS_TRN_LC": 300000}]}`

Step 3: `record_finding(step_name="Check reporting table", result_summary="Data found but ALL rows have ZSCOPE=S_NONE only. Total CS_TRN_LC: 300,000", conclusion="Currency conversion was performed but consolidation stopped. Need to check ownership.", tool_used="check_data_availability", status="needs_further_check")`

Step 4 — Branch to ownership check:
`check_ownership(param_fiscper="2025001", param_cocd="2200")`
Result: `{"result": false, "rows_found": 0}`

Step 5: `record_finding(step_name="Check ownership", result_summary="Ownership NOT found for CoCd 2200 in period 2025001", conclusion="Company 2200 was removed from scope for this period. This explains the S_NONE status.", tool_used="check_ownership", status="issue_found")`

Step 6: `get_investigation_summary()`
</example>

</examples>