Engineering Portfolio Metrics
Overview
Analyze engineering work items exposed through a REST API environment. The three supported analyses are portfolio mix reviews, SLA aging audits, and release readiness assessments. Each analysis requires navigating a set of REST endpoints, resolving duplicate records against canonical primary work items, ignoring stale mirror/legacy fields, and producing a JSON answer that conforms to a supplied template.
Environment and Endpoints
The task prompt supplies <TASK_ENV_BASE_URL> and the file environment_access.md lists the available endpoints. See references/api-endpoints.md for endpoint details and example responses.
Always read environment_access.md first to confirm which endpoints are available for the current task. Not all endpoints appear in every task.
Common endpoints include:
GET /api/work-items — paginated list of work items
GET /api/work-items/{item_id} — single work item detail
GET /api/mix-targets — portfolio mix targets by scope_id
GET /api/sla-policy — SLA response-time thresholds by severity
GET /api/releases — list of releases
GET /api/releases/{release_id} — single release with milestones
GET /api/milestones — milestone definitions
GET /api/dependencies — work-item dependency relationships
GET /api/blockers — blocker records with cause and impact
POST /api/query — restricted SQL query endpoint (use only when the API endpoints don't directly provide the needed data)
Core Rules for All Analyses
Primary vs. Duplicate Records
Some work items are duplicates that point at a canonical (primary) work item. The relationship is expressed through a field such as canonical_id, duplicate_of, or a record status like Duplicate. Always:
- Identify primary records (not duplicates themselves) as the counted population.
- Report duplicate clusters separately (as
duplicate_clusters or excluded_duplicate_ids) so they are not double-counted.
- Never include a duplicate in
included_work_item_ids, included_primary_ids, or any count denominator.
Stale Mirror and Legacy Fields
The environment may include work items with fields like mirror_status, export_status, legacy_category, or similar mirror/export markers. The authoritative fields are the direct work-item fields:
- Use
status (not mirror_status) for work-item lifecycle state.
- Use
portfolio_category (not legacy_category) for portfolio classification.
- Use the work item's own
closed_at, created_at, team, owner, severity, product_area, milestone_id, and release_id fields.
When a template field ignored_mirror_status_and_legacy_category is present, set it to true.
Portfolio Category Classification
The four portfolio categories are always NewFeature, TechDebt, Reliability, and Security. The portfolio_category field on the work item is authoritative. If a work item is missing this field, do not infer a category from title or labels; exclude the item from classification.
Rounding and Precision
- Percentages in mix tables and milestone completion: round to 1 decimal place.
- Rates (breach rate, readiness score): round to 3 decimal places.
- When computing percentages from integer counts, compute
round(100.0 * count / total, 1) for 1-decimal results and round(count / total, 3) for 3-decimal rates.
Stable Ordering
- Work-item ID lists: sort lexicographically (ascending string order).
- Team lists: sort alphabetically.
- Categories in tables: follow the fixed order
NewFeature, TechDebt, Reliability, Security unless the template specifies a different order.
- Duplicate clusters: sort by
primary_id lexicographically; duplicate_ids within each cluster sorted lexicographically.
- Milestone completion: sort by
milestone_id ascending (lexicographic).
- Escalation queue: sort by severity (S1 first, then S2, S3, S4), then within each severity by
created_at ascending (oldest first).
ID Format
Work item IDs follow the pattern WI-24024- with a letter prefix and digits, e.g. WI-24024-A001 or WI-24024-XYZ. Validate against any template regex before finalizing.
Analysis 1: Portfolio Mix Review
Used for portfolio mix tasks where you compare actual close counts against target percentages.
Workflow
- Read the task prompt for scope:
quarter, teams, product_areas (or product_area), and scope_id.
- Fetch
/api/mix-targets and locate the row where scope_id matches the task scope. Extract target_pct values for NewFeature, TechDebt, Reliability, Security.
- Fetch work items in scope. Filter by
quarter, team (in the task team list), and product_area. See references/work-item-model.md for field details.
- Keep only items with authoritative
status of closed or Closed. Do not use mirror_status.
- Identify and set aside:
- Duplicates: items whose
canonical_id or duplicate_of points at another work item, or whose status is Duplicate. These go into excluded_duplicate_ids or duplicate_clusters.
- Cancelled: items with status
cancelled or Cancelled. These go into excluded_cancelled_ids.
- Distractors: items that fall within the scope's time/team/product filters but are not primary closed portfolio work. These go into
excluded_distractor_ids when the template calls for them.
- For each included (primary, closed) work item, read
portfolio_category. Count per category.
- Compute
category_percentages: round(100.0 * count / total_included, 1) for each category.
- Build the
gap_table (or mix_table): for each category in fixed order, include count, actual_pct, target_pct, and gap_pct = actual_pct - target_pct.
- Identify under-invested categories: those with negative
gap_pct, sorted from most negative to least negative.
- Determine the follow-up action:
- If any negative gap exists:
REBALANCE_CAPACITY, primary_category is the one with largest negative gap, rationale_code is LARGEST_NEGATIVE_GAP.
- If no negative gaps:
MAINTAIN_CURRENT_MIX, primary_category is null, secondary_category is null, rationale_code is NO_NEGATIVE_GAPS.
- If a data conflict is detected:
INVESTIGATE_DATA_QUALITY, rationale_code is DATA_CONFLICT.
- Sort
included_work_item_ids by closed_at ascending, then id ascending for ties.
See references/classification-guide.md for category classification rules and examples.
Analysis 2: SLA Aging Audit
Used for SLA audit tasks where you assess overdue reliability/security work items against SLA response-time thresholds.
Workflow
- Read the task prompt for scope:
teams, as_of date, recent_closed_window_days, and sla_categories (or categories).
- Fetch
/api/sla-policy to get the SLA thresholds: max response days per severity level (S1, S2, S3, S4).
- Fetch work items for the specified teams. Filter to the SLA categories (Reliability and/or Security). See references/work-item-model.md for field details.
- Identify primary records (exclude duplicates using the same primary/duplicate logic as in Analysis 1). Report duplicate clusters separately.
- Determine inclusion: a primary work item is included if it is not closed within the
recent_closed_window_days before as_of. Items closed recently (within the window) are considered handled and excluded.
- Determine overdue: an included primary work item is overdue if
created_at + SLA_threshold < as_of. Use the item's severity to look up the threshold in the SLA policy. Items with missing severity should be treated with the most restrictive (shortest) threshold.
- Compute
breach_rate: round(overdue_count / included_primary_count, 3).
- Build aging buckets: compute
days_old = days_between(created_at, as_of). Bucket as 0-3, 4-7, 8-14, 15-30, 31+.
- Build
overdue_counts_by_severity or team_overdue_counts as the template requires.
- Identify the top hotspot: the
(team, owner) pair with the most overdue primary records. For ties, pick the first lexicographically by team then owner. Treat missing owner as UNASSIGNED.
- Build the escalation queue when required: overdue primary IDs sorted by severity (S1 first), then within each severity by
created_at ascending (oldest first).
Analysis 3: Release Readiness
Used for release readiness tasks where you determine whether a named release can ship.
Workflow
- Read the task prompt for the
release_id.
- Fetch
/api/releases/{release_id} for release details including linked milestones.
- Fetch
/api/milestones and cross-reference with the release's milestones to get milestone IDs.
- For each milestone, fetch the work items linked to it. Count primary items only. Count how many are in a completed/closed state. Compute
completion_pct = round(100.0 * complete_primary / primary_total, 1).
- Determine the ship decision:
SHIP: all milestones have completion_pct >= 80.
SHIP_WITH_WATCH: all milestones have completion_pct >= 60 and at least one is < 80.
NO_SHIP: any milestone has completion_pct < 60.
- Identify gating work items: all non-complete release work items (primary only). Sort ascending. Remove duplicates.
- Fetch
/api/blockers for unresolved high-impact blockers. Build blocker_cause_counts keyed by exact cause text (string as-is from the API).
- Fetch
/api/dependencies for dependency chains. A critical dependency chain is an ordered path from a blocked release work item to a non-complete dependency work item. Sort chains lexicographically by the full path.
- Compute
readiness_score: round(completed_primary / primary_total, 3) across all milestones.
Practical Tips
When to Use POST /api/query
Use the /api/query endpoint only when the existing GET endpoints don't provide the data you need. The /api/query endpoint accepts a restricted SQL query. Prefer GET endpoints for work items, mix targets, SLA policy, releases, milestones, blockers, and dependencies.
Pagination
The /api/work-items endpoint may be paginated. Always check response metadata for next links or total counts and fetch all pages before filtering.
Missing Fields
- Work items missing
severity should be treated with the most conservative SLA threshold.
- Work items missing
owner should be counted as UNASSIGNED for hotspot calculations and listed in missing_owner_ids.
- Work items missing
portfolio_category should be excluded from the classified population.
Consistent Field Names
Field names from the API may vary. Always read the actual response JSON to determine exact field names. Common variations: closedAt vs closed_at, createdAt vs created_at, productArea vs product_area. Match what the API actually returns.
Authoritative vs. Stale Fields
Always prefer status over mirror_status, portfolio_category over legacy_category, and the work item's own closed_at over any mirror_closed_at. Duplicates and cancelled items must be excluded from the primary population even if their mirror fields suggest otherwise.
1---2name: eng-portfolio-metrics3description: Engineering portfolio analysis for work-item-oriented REST environments. Covers portfolio mix classification (NewFeature/TechDebt/Reliability/Security) with target-gap analysis, SLA aging audits with breach-rate calculation and duplicate resolution, and release readiness assessments with milestone completion, blocker, and dependency-chain evaluation. Use when a task requires computing portfolio mix percentages and gaps against targets, auditing SLA compliance and overdue work items for specific teams and date windows, or determining ship readiness for a named release.4metadata:5 source: https://skillmd.com/skills/prism-shadow/eng-portfolio-metrics6---78# Engineering Portfolio Metrics910## Overview1112Analyze engineering work items exposed through a REST API environment. The three supported analyses are portfolio mix reviews, SLA aging audits, and release readiness assessments. Each analysis requires navigating a set of REST endpoints, resolving duplicate records against canonical primary work items, ignoring stale mirror/legacy fields, and producing a JSON answer that conforms to a supplied template.1314## Environment and Endpoints1516The task prompt supplies `<TASK_ENV_BASE_URL>` and the file `environment_access.md` lists the available endpoints. See [references/api-endpoints.md](references/api-endpoints.md) for endpoint details and example responses.1718**Always read `environment_access.md` first** to confirm which endpoints are available for the current task. Not all endpoints appear in every task.1920Common endpoints include:2122- `GET /api/work-items` — paginated list of work items23- `GET /api/work-items/{item_id}` — single work item detail24- `GET /api/mix-targets` — portfolio mix targets by scope_id25- `GET /api/sla-policy` — SLA response-time thresholds by severity26- `GET /api/releases` — list of releases27- `GET /api/releases/{release_id}` — single release with milestones28- `GET /api/milestones` — milestone definitions29- `GET /api/dependencies` — work-item dependency relationships30- `GET /api/blockers` — blocker records with cause and impact31- `POST /api/query` — restricted SQL query endpoint (use only when the API endpoints don't directly provide the needed data)3233## Core Rules for All Analyses3435### Primary vs. Duplicate Records3637Some work items are duplicates that point at a canonical (primary) work item. The relationship is expressed through a field such as `canonical_id`, `duplicate_of`, or a record status like `Duplicate`. Always:38391. Identify primary records (not duplicates themselves) as the counted population.402. Report duplicate clusters separately (as `duplicate_clusters` or `excluded_duplicate_ids`) so they are not double-counted.413. Never include a duplicate in `included_work_item_ids`, `included_primary_ids`, or any count denominator.4243### Stale Mirror and Legacy Fields4445The environment may include work items with fields like `mirror_status`, `export_status`, `legacy_category`, or similar mirror/export markers. The authoritative fields are the direct work-item fields:4647- Use `status` (not `mirror_status`) for work-item lifecycle state.48- Use `portfolio_category` (not `legacy_category`) for portfolio classification.49- Use the work item's own `closed_at`, `created_at`, `team`, `owner`, `severity`, `product_area`, `milestone_id`, and `release_id` fields.5051When a template field `ignored_mirror_status_and_legacy_category` is present, set it to `true`.5253### Portfolio Category Classification5455The four portfolio categories are always `NewFeature`, `TechDebt`, `Reliability`, and `Security`. The `portfolio_category` field on the work item is authoritative. If a work item is missing this field, do not infer a category from title or labels; exclude the item from classification.5657### Rounding and Precision5859- Percentages in mix tables and milestone completion: round to **1 decimal place**.60- Rates (breach rate, readiness score): round to **3 decimal places**.61- When computing percentages from integer counts, compute `round(100.0 * count / total, 1)` for 1-decimal results and `round(count / total, 3)` for 3-decimal rates.6263### Stable Ordering6465- Work-item ID lists: sort **lexicographically** (ascending string order).66- Team lists: sort **alphabetically**.67- Categories in tables: follow the fixed order `NewFeature`, `TechDebt`, `Reliability`, `Security` unless the template specifies a different order.68- Duplicate clusters: sort by `primary_id` lexicographically; `duplicate_ids` within each cluster sorted lexicographically.69- Milestone completion: sort by `milestone_id` ascending (lexicographic).70- Escalation queue: sort by severity (S1 first, then S2, S3, S4), then within each severity by `created_at` ascending (oldest first).7172### ID Format7374Work item IDs follow the pattern `WI-24024-` with a letter prefix and digits, e.g. `WI-24024-A001` or `WI-24024-XYZ`. Validate against any template regex before finalizing.7576---7778## Analysis 1: Portfolio Mix Review7980Used for portfolio mix tasks where you compare actual close counts against target percentages.8182### Workflow83841. Read the task prompt for scope: `quarter`, `teams`, `product_areas` (or `product_area`), and `scope_id`.852. Fetch `/api/mix-targets` and locate the row where `scope_id` matches the task scope. Extract `target_pct` values for `NewFeature`, `TechDebt`, `Reliability`, `Security`.863. Fetch work items in scope. Filter by `quarter`, `team` (in the task team list), and `product_area`. See [references/work-item-model.md](references/work-item-model.md) for field details.874. Keep only items with authoritative `status` of `closed` or `Closed`. Do not use `mirror_status`.885. Identify and set aside:89 - **Duplicates**: items whose `canonical_id` or `duplicate_of` points at another work item, or whose status is `Duplicate`. These go into `excluded_duplicate_ids` or `duplicate_clusters`.90 - **Cancelled**: items with status `cancelled` or `Cancelled`. These go into `excluded_cancelled_ids`.91 - **Distractors**: items that fall within the scope's time/team/product filters but are not primary closed portfolio work. These go into `excluded_distractor_ids` when the template calls for them.926. For each included (primary, closed) work item, read `portfolio_category`. Count per category.937. Compute `category_percentages`: `round(100.0 * count / total_included, 1)` for each category.948. Build the `gap_table` (or `mix_table`): for each category in fixed order, include `count`, `actual_pct`, `target_pct`, and `gap_pct = actual_pct - target_pct`.959. Identify under-invested categories: those with negative `gap_pct`, sorted from most negative to least negative.9610. Determine the follow-up action:97 - If any negative gap exists: `REBALANCE_CAPACITY`, `primary_category` is the one with largest negative gap, `rationale_code` is `LARGEST_NEGATIVE_GAP`.98 - If no negative gaps: `MAINTAIN_CURRENT_MIX`, `primary_category` is null, `secondary_category` is null, `rationale_code` is `NO_NEGATIVE_GAPS`.99 - If a data conflict is detected: `INVESTIGATE_DATA_QUALITY`, `rationale_code` is `DATA_CONFLICT`.10011. Sort `included_work_item_ids` by `closed_at` ascending, then `id` ascending for ties.101102See [references/classification-guide.md](references/classification-guide.md) for category classification rules and examples.103104---105106## Analysis 2: SLA Aging Audit107108Used for SLA audit tasks where you assess overdue reliability/security work items against SLA response-time thresholds.109110### Workflow1111121. Read the task prompt for scope: `teams`, `as_of` date, `recent_closed_window_days`, and `sla_categories` (or `categories`).1132. Fetch `/api/sla-policy` to get the SLA thresholds: max response days per severity level (S1, S2, S3, S4).1143. Fetch work items for the specified teams. Filter to the SLA categories (Reliability and/or Security). See [references/work-item-model.md](references/work-item-model.md) for field details.1154. Identify primary records (exclude duplicates using the same primary/duplicate logic as in Analysis 1). Report duplicate clusters separately.1165. Determine inclusion: a primary work item is included if it is not closed within the `recent_closed_window_days` before `as_of`. Items closed recently (within the window) are considered handled and excluded.1176. Determine overdue: an included primary work item is overdue if `created_at + SLA_threshold < as_of`. Use the item's `severity` to look up the threshold in the SLA policy. Items with missing `severity` should be treated with the most restrictive (shortest) threshold.1187. Compute `breach_rate`: `round(overdue_count / included_primary_count, 3)`.1198. Build aging buckets: compute `days_old = days_between(created_at, as_of)`. Bucket as `0-3`, `4-7`, `8-14`, `15-30`, `31+`.1209. Build `overdue_counts_by_severity` or `team_overdue_counts` as the template requires.12110. Identify the top hotspot: the `(team, owner)` pair with the most overdue primary records. For ties, pick the first lexicographically by team then owner. Treat missing owner as `UNASSIGNED`.12211. Build the escalation queue when required: overdue primary IDs sorted by severity (S1 first), then within each severity by `created_at` ascending (oldest first).123124---125126## Analysis 3: Release Readiness127128Used for release readiness tasks where you determine whether a named release can ship.129130### Workflow1311321. Read the task prompt for the `release_id`.1332. Fetch `/api/releases/{release_id}` for release details including linked milestones.1343. Fetch `/api/milestones` and cross-reference with the release's milestones to get milestone IDs.1354. For each milestone, fetch the work items linked to it. Count primary items only. Count how many are in a completed/closed state. Compute `completion_pct = round(100.0 * complete_primary / primary_total, 1)`.1365. Determine the ship decision:137 - `SHIP`: all milestones have `completion_pct >= 80`.138 - `SHIP_WITH_WATCH`: all milestones have `completion_pct >= 60` and at least one is `< 80`.139 - `NO_SHIP`: any milestone has `completion_pct < 60`.1406. Identify gating work items: all non-complete release work items (primary only). Sort ascending. Remove duplicates.1417. Fetch `/api/blockers` for unresolved high-impact blockers. Build `blocker_cause_counts` keyed by exact cause text (string as-is from the API).1428. Fetch `/api/dependencies` for dependency chains. A critical dependency chain is an ordered path from a blocked release work item to a non-complete dependency work item. Sort chains lexicographically by the full path.1439. Compute `readiness_score`: `round(completed_primary / primary_total, 3)` across all milestones.144145---146147## Practical Tips148149### When to Use POST /api/query150151Use the `/api/query` endpoint only when the existing GET endpoints don't provide the data you need. The `/api/query` endpoint accepts a restricted SQL query. Prefer GET endpoints for work items, mix targets, SLA policy, releases, milestones, blockers, and dependencies.152153### Pagination154155The `/api/work-items` endpoint may be paginated. Always check response metadata for `next` links or `total` counts and fetch all pages before filtering.156157### Missing Fields158159- Work items missing `severity` should be treated with the most conservative SLA threshold.160- Work items missing `owner` should be counted as `UNASSIGNED` for hotspot calculations and listed in `missing_owner_ids`.161- Work items missing `portfolio_category` should be excluded from the classified population.162163### Consistent Field Names164165Field names from the API may vary. Always read the actual response JSON to determine exact field names. Common variations: `closedAt` vs `closed_at`, `createdAt` vs `created_at`, `productArea` vs `product_area`. Match what the API actually returns.166167### Authoritative vs. Stale Fields168169Always prefer `status` over `mirror_status`, `portfolio_category` over `legacy_category`, and the work item's own `closed_at` over any `mirror_closed_at`. Duplicates and cancelled items must be excluded from the primary population even if their mirror fields suggest otherwise.