knowledge-one-view-cli/references/initial-context-catalog.md

# Initial Context Catalog

Read this file at skill load time when the ask is about managers, hierarchy, architect productivity, team rollups, or when you need quick business context before touching the CLI catalog. This is a curated seed catalog for fast execution, not a replacement for `fetch-sales-intelligence.mjs --catalog`.

Use this file for org and business-context interpretation. Skip it for routine close-date, SR-by-person, or generic opportunity asks that already map directly to an intent or built-in view.

## Quick Navigation

- Why this file exists: [Why This Exists](#why-this-exists)
- Hierarchy heuristics: [Hierarchy Shortcuts](#hierarchy-shortcuts)
- Verified manager anchors: [Verified Org Anchors](#verified-org-anchors)
- Reusable business translations: [Query Translation Shortcuts](#query-translation-shortcuts)
- SA Attach filters and anchors: [SA Attach Quick Map](#sa-attach-quick-map)
- Final guardrails: [Practical Rules](#practical-rules)

## Why This Exists

- The script catalog is best for CLI and field-contract discovery.
- This file is best for front-loading org or hierarchy context, query translation heuristics, and recurring business shortcuts.
- Use this first when the user already gave a manager name, an email, or wording such as `top architects`, `time do manager`, `produtividade`, `booking/workload por arquiteto`, or `deals WON`.

## Hierarchy Shortcuts

- For SA Attach productivity-style asks, the working source of truth is usually `Knowledge DV - Hours - V2`.
- For any hours/effort rollup, the default metric is 100% of recorded hours: include customer-related work, non-customer/internal work, and Time Off. Exclude any of those categories only when the user explicitly asks for that exclusion or subset.
- In `DV - SE Team`, use `"Effort"."# Hours"` for default hour totals. Use `"Effort"."# Hours (Excl. Time Off)"` only for explicit excluding-Time-Off asks or when a fixed built-in view forces that measure, and disclose that limitation.
- In that dataset, the most useful working assumption is:
  - `SE Team Level 3 Email Address` -> manager scope anchor for many manager-rollup asks.
  - `SE Team Level 4 Email Address` -> direct manager under the level-3 manager.
  - `SE Team Level 5 Email Address` -> architect or IC email for per-person productivity rollups.
  - `SE Team Level 6..8 Email Address` -> often repeats the same IC email. Do not sum across those levels as separate people.
- Do not assume `Security.Entry Point = <manager email>` reproduces the org hierarchy you need. In practice, the entry point can differ from the visible manager email and may return no rows for a valid manager.
- For manager-scoped productivity asks, the fastest stable pattern is:
  1. Filter `Knowledge DV - Hours - V2` by the manager email at the matching hierarchy level.
  2. Aggregate hours by `SE Team Level 5 Email Address`.
  3. Join or intersect with `Knowledge DV - Opportunities - V2` on `Opportunity ID` to apply `Close Date`, `Status`, `Opportunity Value`, `Workload Amount`, territory, and owner context.

## SA Attach Quick Map

- Hierarchy fields: `SE Team Level 3 Email Address` = manager anchor; `SE Team Level 4 Email Address` = direct manager; `SE Team Level 5 Email Address` = architect/IC.
- SA Attach params: `--cluster`, `--solution`, `--revenue-line-status`, `--executive-product-lob`, `--revenue-type-group`, `--sales-credit-type`, `--min-opportunity-probability`.
- SA Attach defaults: `--cluster=Brazil`; `--solution=Cloud Infrastructure - Workloads,Hardware - Bookings,On-Premise Technology - Bookings`; `--revenue-line-status=Open,Won,Won Pending`; `--executive-product-lob=Cloud Infrastructure,Hardware,License`; `--revenue-type-group=NEW,EXPANSION,WORKLOAD`; `--sales-credit-type=QUOTA`; `--min-opportunity-probability=0`.
- SA Attach aliases: `cloud applications` -> `Cloud Applications`; `cloud infrastructure` -> `Cloud Infrastructure`; `hardware` -> `Hardware`; `license` -> `License`; `license and hardware` -> `License,Hardware`; `new` -> `NEW`; `expansion` -> `EXPANSION`; `workload|workloads` -> `WORKLOAD`.

## Verified Org Anchors

Last verified during a live run on `2026-03-27`.

### Higher-level anchors

| Level | Email | Notes |
|---|---|---|
| L1 | `luiz.meisler@oracle.com` | Executive-level anchor seen in SA Attach hours hierarchy. |
| L2 | `marcelo.christianini@oracle.com` | Next-level org anchor above multiple manager branches. |

Keep this section intentionally small. Only verified hierarchy anchors that materially shortcut discovery should stay here; one-off example managers should not.

## Query Translation Shortcuts

| Ask shape | Fastest reliable translation |
|---|---|
| `vendedor`, `sales rep`, `lider de vendas` | Interpret as `territory owner` by default for opportunity/pipeline asks unless the user explicitly requests another role. |
| `Top arquitetos do manager X em WON com close date em janela Y` | Filter `Knowledge DV - Hours - V2` by manager hierarchy level, aggregate `# Opportunity Hours` by `SE Team Level 5 Email Address`, then intersect with `Knowledge DV - Opportunities - V2` `Opportunity ID`s filtered by `Close Date` and `Status = 'Won'`. |
| `Mostrar booking/workload dos top arquitetos` | Use the same top-architect result, then de-duplicate by `architectEmail + opportunityId` before summing `Opportunity Value` and `Workload Amount` from `Knowledge DV - Opportunities - V2`. |
| `Quais clientes compoem o total do arquiteto` | Reuse the same de-duplicated architect or opportunity set and pull `Customer Name`, `Opportunity Value`, and `Workload Amount` from `Knowledge DV - Opportunities - V2`. |
| `Preciso descobrir qual nível representa o manager` | Probe `SE Team Level 1..8 Email Address` with a `%surname%` or exact-email search in `Knowledge DV - Hours - V2` before building the final query. |
| `Quero deals WON do time do manager` | Prefer `Knowledge DV - Opportunities - V2` for `Close Date`, `Status`, `Opportunity Value`, `Workload Amount`, territory, and owner context; prefer `Knowledge DV - Hours - V2` for hierarchy ownership and allocated hours. |
| `Horas/atividades sem cliente`, `não relacionadas a oportunidades`, `atividades internas` | This is an explicit subset request. In `DV - SE Team` effort reads, classify as no-customer only when SR Number, Customer Name, and Opportunity ID are all `Unspecified`; any populated SR/customer/opportunity means customer-related. |

## Practical Rules

- Prefer `--query` for ad hoc joins, filters, and groupings when it can express the ask cleanly.
- Prefer `--sql` only when you need a dataset the normal `Security Entry Point` filter cannot express or when you must query XSA hierarchy columns directly.
- Do not trust `Won Flag` from the hours dataset as the only `WON` filter for business reporting. Use `Knowledge DV - Opportunities - V2` `Opportunity Status = 'Won'` plus the required close-date window.
- For effort/hour analysis, do not apply customer-linkage filters by default. When the user explicitly requests customer vs. non-customer classification, `Unspecified` is the workbook's absence marker; do not test only for SQL `NULL` when determining whether an effort row lacks customer linkage.
- Validated FY26 my-team no-customer task types: `Administration`, `Content Creation`, `Partner Activities`, `Sales Planning`, `Training Delivery`, and `Training/Personal Development - Taken`. Treat this as a validated pattern, not the primary rule; the primary rule is the three-field `Unspecified` linkage signal.
- Customer-related FY26 my-team task types observed: `Config`, `Preparation`, and `Travel`; `Delivery` and `Follow-up` were mostly customer-related and had small cases with SR/customer but no opportunity ID, so keep them customer-related unless all three linkage fields are `Unspecified`.
- Use `Knowledge DV - Opportunities - V2` and the other Knowledge DV views for org-wide reads whose hierarchy starts at Latin America leadership.
- Use `DV - SE Team` only for self-scoped questions where "my team" really means the executing user and the people below that user, plus the normal SR and session-context questions.
- Do not use `DV - SE Team` as generic fallback for manager, territory, owner, or org-wide commercial reads.
- When crossing org-wide opportunities/workloads with team-scoped resource enrichment, keep every org-wide row and leave the resource fields empty when no team match exists.
- When listing clients and values for each architect, sum booking and workload only once per `architectEmail + opportunityId`.
- If the SQL gets quote-heavy on Windows PowerShell, use the SQL runner helper script documented in [script-catalog.md](script-catalog.md) instead of passing a long `--sql` string directly through the shell.

## Suggested First Read Order

1. This file for manager or hierarchy or business context.
2. [script-catalog.md](script-catalog.md) only if the CLI contract is still unclear.
3. `fetch-sales-intelligence.mjs --catalog` only if the data contract is still unclear after the two files above.