Portfolio Analyzer
Analyze engineering portfolio data through a standardized task-environment REST
API. This skill covers three analysis types: portfolio mix reviews, SLA aging
audits, and release readiness assessments. Read the relevant reference files
when you need deeper detail on the data model, API endpoints, or output
conventions.
Core Workflow
Every portfolio analysis follows the same four-phase pattern:
- Fetch - collect all needed data from the environment API.
- Clean - separate primary records from duplicates, cancelled items, and
stale mirror/distractor records.
- Classify - assign each primary item to exactly one portfolio category.
- Compute and Output - calculate aggregates, gaps, rates, and produce a
single JSON answer matching the provided answer template.
Fetching Data
The environment lives at <TASK_ENV_BASE_URL>. Read
references/api-endpoints.md for the full endpoint
catalog and SQL query table schema.
Start by fetching all relevant data in parallel where possible. The standard
pattern:
- Portfolio mix: fetch work items filtered by scope or team/quarter, plus
mix targets.
- SLA audit: fetch work items, SLA policy, then determine the as-of date and
window from the prompt.
- Release readiness: fetch the release by ID, then fetch its milestones,
work items, blockers, and dependencies in parallel.
Use GET endpoints as your primary tool. Only reach for POST /api/query when
you need a cross-entity join that cannot be done efficiently with client-side
filtering on the REST results. When you do use SQL, write SQLite-compatible
SELECT statements.
Cleaning: Primary vs. Non-Primary Records
A work item is primary (countable) only when ALL three conditions hold:
status is NOT cancelled.
duplicate_of is null (it is not a duplicate of another item).
mirror_status is null or empty (not a stale mirror/export record).
Items that fail any condition go into exclusion lists. Read
references/data-model.md for the full field
reference.
Never use mirror_status or legacy_category as source of truth. Always
use status and category from the work item object. Mirror fields exist
alongside authoritative fields in the API responses but contain stale data.
Duplicate grouping: when item.duplicate_of is non-null, group duplicates
by their duplicate_of value. The referenced item is the primary; the current
item is the duplicate. Sort duplicate clusters by primary_id ascending.
Classifying Work into Categories
Every work item maps to exactly one of these four portfolio categories:
NewFeature -> TechDebt -> Reliability -> Security
The authoritative source is the category field. When the prompt says to use
portfolio category conventions for resolving conflicting signals, apply this
priority order:
- The
category field, when present and valid.
- The
type field: Bug -> Reliability (or Security if the title contains
security keywords), Story -> NewFeature, Task -> TechDebt.
- Keyword signals in the
title field.
See references/data-model.md for the full keyword
mapping.
Computing Results
After cleaning and classifying, compute the aggregates the task asks for. Three
common analysis types are covered below.
Analysis Type: Portfolio Mix Review
- Count primary closed work items per category.
- Read the target mix percentages from
/api/mix-targets for the matching
scope_id.
- Compute actual percentages:
(category_count / total_primary) * 100, rounded
to 1 decimal place.
- Compute gaps:
gap_pct = actual_pct - target_pct (rounded to 1 decimal).
- Identify under-invested categories: those with negative gap_pct, ordered from
most negative to least negative.
- The follow-up/recommended action:
REBALANCE_CAPACITY targeting the category
with the largest negative gap, using LARGEST_NEGATIVE_GAP as rationale.
Sort included work item IDs by closed_at ascending, then by id ascending.
Excluded distractor/duplicate/cancelled IDs follow the same sort.
Analysis Type: SLA Aging Audit
- Determine the primary population: work items in scope for the given teams,
matching the SLA-relevant categories (typically Reliability and Security).
- Determine overdue items: primary items where the SLA target resolution
duration (from
/api/sla-policy, keyed by severity) has elapsed relative to
created_at and the as-of date. Items closed within the recent window do not
count as overdue.
- Compute aging buckets by days since
created_at (for open items) or days
open before closure (for recently closed). Bucket boundaries: 0-3, 4-7, 8-14,
15-30, 31+.
- Find the owner+team hotspot: the owner/team pair with the most overdue
primary records. Use
UNASSIGNED when owner is null.
- Build duplicate clusters from items where
duplicate_of is non-null.
- Compute breach rate:
overdue_primary_count / included_primary_count, rounded
to 3 decimal places.
- For escalation queues: sort overdue primary items by severity descending,
then
created_at ascending, then ID ascending.
Analysis Type: Release Readiness Assessment
- Fetch the release by ID, then fetch its milestones, all associated work items,
blockers, and dependencies.
- Determine milestone completion: for each milestone, count completed primary
work items vs. total primary work items. Completion percentage is rounded to
1 decimal place. Sort milestones by milestone_id ascending.
- Identify gating work items: non-complete primary release work items that block
readiness. Sort ascending with no duplicates.
- Count unresolved high-impact blockers by exact cause text. Only count blockers
where
resolved is false and impact is high.
- Trace critical dependency chains: follow
dependencies to find paths from
blocked release work items through to non-complete dependencies. Each chain
is an ordered array of work item IDs. Sort chains lexicographically by the
full path.
- Compute readiness score:
completed_primary / total_primary, rounded to 3
decimal places.
- Ship decision logic:
SHIP when readiness_score >= 0.90 and no unresolved high-impact blockers.
SHIP_WITH_WATCH when readiness_score >= 0.75 but with minor concerns.
NO_SHIP when readiness_score < 0.75 or unresolved high-impact blockers
exist on gating items.
Output Conventions
Read references/conventions.md for the full
sorting and precision reference. The key rules:
- IDs: lexicographic ascending.
- Teams: alphabetical ascending.
- Categories: always
NewFeature, TechDebt, Reliability, Security order.
- Percentages: 1 decimal place.
- Rates: 3 decimal places.
- Gaps:
actual_pct - target_pct, in percentage points.
Answer Template
Every task provides an answer_template.json in the input payloads. Read it
before computing results. It defines the exact JSON shape, required fields,
allowed enum values, and any additional constraints. Your output must match that
schema exactly - no extra fields, no missing required fields, no prose outside
the JSON object.
Pay close attention to field naming differences between templates. For example,
one portfolio mix template may use gap_table and under_invested_categories
while another uses mix_table and largest_deficit_category. Do not assume
uniform naming; always read the template.
Common Pitfalls
- Treating
mirror_status or legacy_category as truth instead of status and
category.
- Counting duplicates or cancelled items in primary totals.
- Forgetting to round percentages to 1 decimal place or rates to 3 decimal places.
- Using the wrong category order in tables (must be NewFeature, TechDebt,
Reliability, Security).
- Computing gap as
target - actual instead of actual - target.
- Using stale mirror/export status fields to determine completion instead of
authoritative
status.
- Including recently-closed items in the overdue count for SLA audits when the
task specifies a recent closed window.
- Not sorting IDs lexicographically (which treats digits character-by-character,
not numerically).
1---2name: portfolio-analyzer3description: Analyze engineering portfolio data from a shared task-environment REST API. Use this skill whenever the user asks about portfolio mix reviews, SLA aging audits, release readiness assessments, work item classification, engineering capacity planning, or any task that references a TASK_ENV_BASE_URL with work items, mix targets, releases, milestones, blockers, dependencies, or SLA policies. This skill covers portfolio category analysis, SLA breach detection, release gating, dependency chain tracing, and duplicate/distractor record handling. Even if the user does not mention "portfolio" explicitly, use this skill for any task that queries work items grouped by scope, team, quarter, or release in an engineering-operations context.4metadata:5 source: https://skillmd.com/skills/prism-shadow/portfolio-analyzer6---78# Portfolio Analyzer910Analyze engineering portfolio data through a standardized task-environment REST11API. This skill covers three analysis types: portfolio mix reviews, SLA aging12audits, and release readiness assessments. Read the relevant reference files13when you need deeper detail on the data model, API endpoints, or output14conventions.1516## Core Workflow1718Every portfolio analysis follows the same four-phase pattern:19201. **Fetch** - collect all needed data from the environment API.212. **Clean** - separate primary records from duplicates, cancelled items, and22 stale mirror/distractor records.233. **Classify** - assign each primary item to exactly one portfolio category.244. **Compute and Output** - calculate aggregates, gaps, rates, and produce a25 single JSON answer matching the provided answer template.2627## Fetching Data2829The environment lives at `<TASK_ENV_BASE_URL>`. Read30[references/api-endpoints.md](references/api-endpoints.md) for the full endpoint31catalog and SQL query table schema.3233Start by fetching all relevant data in parallel where possible. The standard34pattern:3536- **Portfolio mix**: fetch work items filtered by scope or team/quarter, plus37 mix targets.38- **SLA audit**: fetch work items, SLA policy, then determine the as-of date and39 window from the prompt.40- **Release readiness**: fetch the release by ID, then fetch its milestones,41 work items, blockers, and dependencies in parallel.4243Use GET endpoints as your primary tool. Only reach for `POST /api/query` when44you need a cross-entity join that cannot be done efficiently with client-side45filtering on the REST results. When you do use SQL, write SQLite-compatible46SELECT statements.4748## Cleaning: Primary vs. Non-Primary Records4950A work item is **primary** (countable) only when ALL three conditions hold:51521. `status` is NOT `cancelled`.532. `duplicate_of` is `null` (it is not a duplicate of another item).543. `mirror_status` is `null` or empty (not a stale mirror/export record).5556Items that fail any condition go into exclusion lists. Read57[references/data-model.md](references/data-model.md) for the full field58reference.5960**Never** use `mirror_status` or `legacy_category` as source of truth. Always61use `status` and `category` from the work item object. Mirror fields exist62alongside authoritative fields in the API responses but contain stale data.6364**Duplicate grouping**: when `item.duplicate_of` is non-null, group duplicates65by their `duplicate_of` value. The referenced item is the primary; the current66item is the duplicate. Sort duplicate clusters by primary_id ascending.6768## Classifying Work into Categories6970Every work item maps to exactly one of these four portfolio categories:7172```73NewFeature -> TechDebt -> Reliability -> Security74```7576The authoritative source is the `category` field. When the prompt says to use77portfolio category conventions for resolving conflicting signals, apply this78priority order:79801. The `category` field, when present and valid.812. The `type` field: `Bug` -> Reliability (or Security if the title contains82 security keywords), `Story` -> NewFeature, `Task` -> TechDebt.833. Keyword signals in the `title` field.8485See [references/data-model.md](references/data-model.md) for the full keyword86mapping.8788## Computing Results8990After cleaning and classifying, compute the aggregates the task asks for. Three91common analysis types are covered below.9293### Analysis Type: Portfolio Mix Review94951. Count primary closed work items per category.962. Read the target mix percentages from `/api/mix-targets` for the matching97 `scope_id`.983. Compute actual percentages: `(category_count / total_primary) * 100`, rounded99 to 1 decimal place.1004. Compute gaps: `gap_pct = actual_pct - target_pct` (rounded to 1 decimal).1015. Identify under-invested categories: those with negative gap_pct, ordered from102 most negative to least negative.1036. The follow-up/recommended action: `REBALANCE_CAPACITY` targeting the category104 with the largest negative gap, using `LARGEST_NEGATIVE_GAP` as rationale.105106Sort included work item IDs by `closed_at` ascending, then by `id` ascending.107Excluded distractor/duplicate/cancelled IDs follow the same sort.108109### Analysis Type: SLA Aging Audit1101111. Determine the primary population: work items in scope for the given teams,112 matching the SLA-relevant categories (typically Reliability and Security).1132. Determine overdue items: primary items where the SLA target resolution114 duration (from `/api/sla-policy`, keyed by severity) has elapsed relative to115 `created_at` and the as-of date. Items closed within the recent window do not116 count as overdue.1173. Compute aging buckets by days since `created_at` (for open items) or days118 open before closure (for recently closed). Bucket boundaries: 0-3, 4-7, 8-14,119 15-30, 31+.1204. Find the owner+team hotspot: the owner/team pair with the most overdue121 primary records. Use `UNASSIGNED` when owner is null.1225. Build duplicate clusters from items where `duplicate_of` is non-null.1236. Compute breach rate: `overdue_primary_count / included_primary_count`, rounded124 to 3 decimal places.1257. For escalation queues: sort overdue primary items by severity descending,126 then `created_at` ascending, then ID ascending.127128### Analysis Type: Release Readiness Assessment1291301. Fetch the release by ID, then fetch its milestones, all associated work items,131 blockers, and dependencies.1322. Determine milestone completion: for each milestone, count completed primary133 work items vs. total primary work items. Completion percentage is rounded to134 1 decimal place. Sort milestones by milestone_id ascending.1353. Identify gating work items: non-complete primary release work items that block136 readiness. Sort ascending with no duplicates.1374. Count unresolved high-impact blockers by exact cause text. Only count blockers138 where `resolved` is false and `impact` is high.1395. Trace critical dependency chains: follow `dependencies` to find paths from140 blocked release work items through to non-complete dependencies. Each chain141 is an ordered array of work item IDs. Sort chains lexicographically by the142 full path.1436. Compute readiness score: `completed_primary / total_primary`, rounded to 3144 decimal places.1457. Ship decision logic:146 - `SHIP` when readiness_score >= 0.90 and no unresolved high-impact blockers.147 - `SHIP_WITH_WATCH` when readiness_score >= 0.75 but with minor concerns.148 - `NO_SHIP` when readiness_score < 0.75 or unresolved high-impact blockers149 exist on gating items.150151## Output Conventions152153Read [references/conventions.md](references/conventions.md) for the full154sorting and precision reference. The key rules:155156- **IDs**: lexicographic ascending.157- **Teams**: alphabetical ascending.158- **Categories**: always `NewFeature, TechDebt, Reliability, Security` order.159- **Percentages**: 1 decimal place.160- **Rates**: 3 decimal places.161- **Gaps**: `actual_pct - target_pct`, in percentage points.162163## Answer Template164165Every task provides an `answer_template.json` in the input payloads. Read it166before computing results. It defines the exact JSON shape, required fields,167allowed enum values, and any additional constraints. Your output must match that168schema exactly - no extra fields, no missing required fields, no prose outside169the JSON object.170171Pay close attention to field naming differences between templates. For example,172one portfolio mix template may use `gap_table` and `under_invested_categories`173while another uses `mix_table` and `largest_deficit_category`. Do not assume174uniform naming; always read the template.175176## Common Pitfalls177178- Treating `mirror_status` or `legacy_category` as truth instead of `status` and179 `category`.180- Counting duplicates or cancelled items in primary totals.181- Forgetting to round percentages to 1 decimal place or rates to 3 decimal places.182- Using the wrong category order in tables (must be NewFeature, TechDebt,183 Reliability, Security).184- Computing gap as `target - actual` instead of `actual - target`.185- Using stale mirror/export status fields to determine completion instead of186 authoritative `status`.187- Including recently-closed items in the overdue count for SLA audits when the188 task specifies a recent closed window.189- Not sorting IDs lexicographically (which treats digits character-by-character,190 not numerically).