From 5ea33e353e667c72250e9ef39e7b46fc95f5084f Mon Sep 17 00:00:00 2001 From: Marcelo Arbore Date: Tue, 5 May 2026 11:51:57 -0300 Subject: [PATCH] =?UTF-8?q?Commit=20pre-revisao=20de=20simplifica=C3=A7?= =?UTF-8?q?=C3=A3o=20e=20elegancia=20do=20superpowers?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- SKILL.md | 8 ++++++++ references/initial-context-catalog.md | 6 ++++++ 2 files changed, 14 insertions(+) diff --git a/SKILL.md b/SKILL.md index 5dca83a..5d8420f 100644 --- a/SKILL.md +++ b/SKILL.md @@ -142,6 +142,10 @@ Use `--sql` only when `--query` cannot express the ask cleanly. ## Data-Specific Rules - For manager or hierarchy asks, start with [references/initial-context-catalog.md](references/initial-context-catalog.md) before touching the CLI catalog. +- For any effort/hour allocation ask, default to 100% of recorded hours. Include customer-related work, non-customer/internal work, and Time Off unless the user explicitly asks to exclude one of those categories. +- For `DV - SE Team` effort/hour reads, use `"Effort"."# Hours"` as the default total-hours measure. Use `"Effort"."# Hours (Excl. Time Off)"` only when the user explicitly asks to exclude Time Off or when a specific built-in view forces that metric; if forced, disclose the limitation. +- For `Knowledge DV - Hours - V2` or other XSA hour reads, prefer the available total-hours measure that includes Time Off. If only an excluding-Time-Off alias such as `hoursExcludingTimeOff` is available, probe or use `--sql` to validate a total-hours field before falling back. +- Do not filter hours to only customer, only non-customer, only opportunity-linked, only internal, or only Time Off unless the user explicitly requests that subset. - For generic opportunity and pipeline asks, prefer `opportunities-default`. - For close-date asks, prefer `opportunities-close-date`, `opportunities-close-month`, or `opportunities-close-window`. - For fiscal-quarter asks, prefer `--quarter` with `FY26-Q4`, `Q4 FY26`, or `current-quarter`. @@ -165,6 +169,9 @@ Use `--sql` only when `--query` cannot express the ask cleanly. - Use `--owner-email` for direct territory-owner filters and `--owner-manager-email` for owner-hierarchy filters on SA Attach workload reads. - Use `--forecast-type` for natural-language asks such as `forecast`, `upside`, or `won` on SA Attach workload reads. - Keep opportunity-linked monetary outputs consistent as `bookingValue` and `workloadAmount`. +- For `DV - SE Team` effort/hour reads about activities not related to customers, apply this classification only when the user explicitly asks for non-client, client/non-client splits, internal work, or customer-related filtering. Treat `Unspecified` in all three linkage fields (`Service Request"."SR Number"`, `"Customer"."Customer Name"`, and `"Opportunity"."Opportunity ID"`) as the signal for no customer relationship. Any populated SR, customer, or opportunity means the effort is customer-related. +- For the current validated FY26 my-team pattern, the task types that matched the no-customer signal were `Administration`, `Content Creation`, `Partner Activities`, `Sales Planning`, `Training Delivery`, and `Training/Personal Development - Taken`. `Config`, `Preparation`, and `Travel` were customer-related; `Delivery` and `Follow-up` were mostly customer-related, with small cases that had SR/customer but `Opportunity ID = 'Unspecified'`, so do not classify them as non-customer solely by task type. +- When answering "non-client", "sem cliente", "sem oportunidade", or "atividades internas" effort asks, prefer validating/reporting by the `Unspecified` linkage signal first and only use task type names as a helpful summary of the observed pattern. - Treat `Knowledge DV - Opportunities - V2` as the normal source for pipeline, opportunity, won, close date, territory, owner, booking, and workload. - Interpret user wording `vendedor`, `sales rep`, and `lider de vendas` as `territory owner` by default. - Treat org-wide-capable XSA datasets as org-wide reads in `--scope auto`: `Knowledge DV - Opportunities - V2`, `Knowledge DV - Hours - V2`, `Knowledge DV - Presales Involvement Aux - V1`, and `Knowledge DV - Revn Lines by SE`. @@ -205,6 +212,7 @@ User-facing answer contract: - If date windows, weeks, quarters, or "current" wording were interpreted, state the resolved period and the date field being filtered. For commercial SA Attach close-window answers, say that the window filters `Revenue Line Close Date`. - If user wording required role interpretation, state it briefly, for example `vendedor`/`sales rep`/`lider de vendas` interpreted as `territory owner`, or short Oracle uid normalized to `@oracle.com`. - If SR, resource, manager, or workload enrichment involved implicit joins, state the join assumption: `opportunityId` is the confirmed linkage; same-resource same-customer SRs without usable `opportunityId` are only fallback candidates; and current-team enrichment can leave unmatched org-wide rows with empty resource fields. +- For hour/effort answers, state whether the reported metric includes Time Off and whether customer and non-customer/internal hours were included. The default is 100% of recorded hours unless an explicit user filter says otherwise. - Always include API effort and data-shape caveats: `Raw rows pulled from the API: X`; whether the result hit the requested/default limit; any `warnings`; and whether displayed monetary fields use truncated `k` values while `raw` keeps backend-native values. - Never describe the numbers as "all company", "all Brazil", or "complete pipeline" unless the disclosed `scope`, filters, defaults, and limits actually support that statement. diff --git a/references/initial-context-catalog.md b/references/initial-context-catalog.md index 84ea880..46e9fc9 100644 --- a/references/initial-context-catalog.md +++ b/references/initial-context-catalog.md @@ -22,6 +22,8 @@ Use this file for org and business-context interpretation. Skip it for routine c ## 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. @@ -63,12 +65,16 @@ Keep this section intentionally small. Only verified hierarchy anchors that mate | `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.