Engineering Portfolio Analysis
Overview
This skill covers three analytical workflows against a shared engineering work-item REST API:
- Portfolio Mix Review — Classify closed work items into four categories (NewFeature, TechDebt, Reliability, Security), compare count-based actual mix against target mix percentages, identify under-invested categories, and recommend a rebalance action.
- SLA Aging Audit — Filter primary (non-duplicate, non-cancelled) work items by team and SLA-relevant categories, compute aging buckets relative to an as-of date, identify overdue items against SLA policy by severity, flag duplicate clusters, missing owners, and calculate breach rate.
- Release Readiness Assessment — For a specific release, compute milestone completion metrics, identify gating (non-complete) work items, count unresolved high-impact blockers by cause, trace critical dependency chains, and produce a readiness score and ship decision.
All workflows share a common data model. See references/data_model.md for the full field reference and API endpoint details.
Common Rules for All Workflows
Authoritative vs Stale Fields
- The
status field on each work item is authoritative. Ignore mirror_status — it is a stale export snapshot and does not reflect current state.
- The
legacy_category field is a legacy hint only. Do not use it as the primary classification signal.
- For release-related work, use the work item's
release_id and milestone_id fields, not any mirrored or export-derived fields.
Duplicate and Cancelled Handling
- Work items with
status "Duplicate" must be excluded from primary counts. Their duplicate_of field points to the canonical item. Report excluded duplicate IDs separately.
- Work items with
status "Cancelled" must be excluded from primary counts. Report excluded cancelled IDs separately.
- A Duplicate record may itself have been closed within the scope window. Still exclude it from primary counts regardless of its
closed_at date.
Primary vs Non-Primary Records
- A "primary" work item is one whose
status is not "Duplicate" and not "Cancelled".
- Primary items are the denominator for all counts, percentages, and rates.
- Duplicate clusters (canonical to duplicates) should be reported as metadata but must not inflate primary counts.
Ordering Conventions
- Sort work-item ID lists lexicographically (ASCII sort) unless the task template specifies a different order (e.g.
closed_at ascending then id ascending).
- Sort team lists alphabetically.
- Sort gap/mix table rows in the fixed category order: NewFeature, TechDebt, Reliability, Security.
- Sort duplicate clusters by
primary_id lexicographically, with duplicate_ids within each cluster sorted lexicographically.
Numeric Precision
- Percentages derived from counts: divide the category count by the primary total, multiply by 100, round to 1 decimal place (portfolio mix tasks) or 3 decimal places (breach rate, readiness score).
- Gap values:
actual_pct - target_pct, rounded to the same precision as the percentages.
- When a category has zero items and the total is zero, treat percentages as 0.0.
Workflow 1: Portfolio Mix Review
Scope Determination
- Read the task prompt for: scope_id, quarter (e.g. 2025-Q4), teams, product area(s), and target scope_id.
- Fetch mix targets from
GET /api/mix-targets and find the row whose scope_id exactly matches the target scope_id from the prompt. This row provides the target percentages: new_feature_pct, tech_debt_pct, reliability_pct, security_pct. These are decimals (e.g. 0.34 = 34%); multiply by 100 and round to 1 decimal place for display.
- The quarter defines the closed-date window: a closed work item's
closed_at must fall within the calendar quarter (e.g. 2025-Q4 = 2025-10-01 through 2025-12-31).
Filtering In-Scope Work Items
Fetch all work items from GET /api/work-items. Apply these filters:
team matches one of the prompt teams
product_area matches one of the prompt product areas (if specified)
closed_at falls within the quarter window and is not null
status is not "Duplicate" and not "Cancelled"
Watch for "distractor" records — items that match on team and product_area but use a different data schema (e.g. wrapped in a work_item sub-object with legacy_category instead of work_type). Exclude these from the primary mix and report them separately when the template has an exclusion field for them.
Portfolio Category Classification
Assign each included primary work item to exactly one of: NewFeature, TechDebt, Reliability, Security.
Classification uses a three-signal cascade. Start with the strongest signal and resolve conflicts in order:
Signal 1 — work_type (strongest):
Security, Compliance to Security
Reliability to Reliability
Incident to Reliability (incident follow-ups represent reliability investment), unless labels are exclusively security (cve/auth/encryption) with no reliability signals
Feature to NewFeature (unless overridden by labels)
Enhancement to check labels; defaults toward Security when no clear feature/reliability signal
Refactor, Chore, Dependency to TechDebt
Bug to check labels; with reliability labels to Reliability; with security labels to Security; otherwise to TechDebt
Signal 2 — labels (secondary):
- Labels containing
security, cve, encryption push toward Security
- Labels containing
reliability, incident, outage, latency push toward Reliability
- Labels containing
cleanup, refactor, migration, dependency push toward TechDebt
- Labels containing
feature, rollout (without security/reliability override) push toward NewFeature
Signal 3 — title (tiebreaker only):
- When work_type and labels conflict or are ambiguous, the title text can break the tie. Keywords: "security", "cve", "encrypt", "auth" to Security; "reliability", "incident", "outage", "latency", "retry", "flaky" to Reliability; "cleanup", "refactor", "migrat" to TechDebt; "feature", "rollout", "enhancement" to NewFeature.
Resolution priority: Security signals dominate Reliability signals dominate TechDebt signals dominate NewFeature. When an item has both security and reliability signals, classify as Security. When it has reliability and tech-debt signals, classify as Reliability. The presence of any security-relevant label (security, cve, encryption) on a Feature or Enhancement work_type overrides the NewFeature default and classifies it as Security.
Mix Gap Analysis
- Count items per category to
category_counts.
- Compute actual percentages:
(count / total_primary) * 100, rounded to 1 decimal.
- Compare against target percentages from the mix-target row.
- Compute gaps:
actual_pct - target_pct.
- Identify under-invested categories: those with negative gap, ordered from most negative to least negative.
- Recommend follow-up action:
REBALANCE_CAPACITY with rationale_code LARGEST_NEGATIVE_GAP when any gap is negative; set primary_category to the most-negative-gap category and secondary_category to the second-most-negative (or null if none).
MAINTAIN_CURRENT_MIX with rationale_code NO_NEGATIVE_GAPS when no gaps are negative.
INVESTIGATE_DATA_QUALITY with rationale_code DATA_CONFLICT when the data has conflicts that prevent a clean recommendation.
Workflow 2: SLA Aging Audit
Scope Determination
- Read the task prompt for: teams, SLA-relevant categories (typically Reliability and Security), as-of date, and recent closed window in days.
- Fetch SLA policy from
GET /api/sla-policy. This returns an array of {severity, days_to_due} objects. Map each severity level to its SLA due window.
Filtering In-Scope Work Items
Fetch all work items from GET /api/work-items. Apply:
team matches one of the prompt teams
- The item belongs to one of the SLA-relevant categories (classify using the same portfolio category rules as Workflow 1)
status is not "Cancelled" (Duplicate items are excluded from primary but tracked in duplicate clusters)
closed_at is either null (open work) or falls within the recent closed window (closed_at >= as_of_date - window_days)
Primary vs Duplicate Separation
- Work items with
status "Duplicate" form duplicate clusters. Group them by duplicate_of (the canonical primary id).
- The canonical primary item must itself be in scope. If a duplicate points to an item outside scope, still report the cluster but do not count the canonical in primary totals.
- All non-Duplicate, non-Cancelled items are primary.
SLA Breach Calculation
For each primary item:
- If
closed_at is not null, the item is already closed — it is not overdue.
- If
closed_at is null, compute age: as_of_date - created_at in days.
- Look up the SLA
days_to_due for the item's severity.
- If
age > days_to_due, the item is overdue.
Aging Buckets
For each primary item (open or recently closed), compute age from created_at to as_of_date in days. Bucket into: 0-3, 4-7, 8-14, 15-30, 31+. Count items per bucket.
Hotspot and Team Overdue
- Compute overdue counts per team.
- Find the owner/team pair with the most overdue primary items. If multiple tie, use the one with the owner appearing first alphabetically. If owner is missing, use "UNASSIGNED".
- Report
missing_owner_ids: primary items with null/empty owner.
Breach Rate
breach_rate = overdue_primary_count / included_primary_count, rounded to exactly 3 decimal places.
Escalation Queue (when required)
Order overdue primary items by priority for follow-up. Use this precedence: S1 before S2 before S3 before S4. Within the same severity, order by earliest created_at first (oldest items first).
Workflow 3: Release Readiness Assessment
Scope Determination
- Read the task prompt for the release ID under review.
- Fetch the release from
GET /api/releases/{release_id} or from the full list at GET /api/releases.
- Fetch all milestones from
GET /api/milestones. Filter to those whose release_id matches the target release.
- Fetch all work items, blockers, and dependencies from their respective endpoints.
Milestone Completion
For each milestone of the release (sorted by milestone_id ascending):
- Find all work items whose
milestone_id matches and whose status is not "Duplicate" (primary work items).
- Count completed primary items: those with
status in the completed set. Treat any of these as completed: Done, Deployed, Verified, Closed, Resolved (use the exact status strings observed in the API).
- Compute
completion_pct = (complete_primary / primary_total) * 100, rounded to 1 decimal.
Gating Work Items
Identify non-complete release work items that gate readiness:
- Work items whose
release_id matches the target release
status is not in the completed set AND not "Duplicate"
- Sort ascending, no duplicates.
Blocker Analysis
Fetch blockers from GET /api/blockers. Filter for:
release_id matches the target release
severity is "High" or "Critical" (high-impact only)
status is not "Resolved" (unresolved only)
Count by exact cause string. Use the cause text verbatim as the key.
Critical Dependency Chains
Fetch all dependencies from GET /api/dependencies. For each dependency edge:
- The
blocked_id is the release work item that is blocked.
- The
depends_on_id is the work item it depends on.
- The
relation describes the nature.
A critical dependency chain exists when: a release work item (has the target release_id) is blocked_id in a dependency edge, AND the depends_on_id work item is itself not complete (status not in completed set).
Build chains by walking from the blocked release work item. If the dependency is itself blocked by another item (transitive), include the full ordered path: [blocked_release_item, ..., non_complete_dependency]. Each link in the chain represents one dependency edge.
Sort chains lexicographically by the full path (compare the string representation of the path array).
If no such chains exist, return an empty array.
Readiness Score
readiness_score = total_completed_primary_release_items / total_primary_release_items, rounded to 3 decimal places.
Count across all milestones: sum of completed primary items divided by sum of all primary items for the release.
Ship Decision
SHIP when readiness_score >= 0.95 AND there are zero unresolved high-impact blockers AND zero gating work items.
SHIP_WITH_WATCH when readiness_score >= 0.80 AND there are zero unresolved high-impact blockers, but there are gating work items.
NO_SHIP when there are unresolved high-impact blockers, OR readiness_score < 0.80, OR there are gating work items of a severity or nature that block release confidence.
When in doubt between SHIP_WITH_WATCH and NO_SHIP, the presence of any unresolved High or Critical blocker is decisive for NO_SHIP.
Resources
- references/data_model.md — Complete field reference for every API entity, endpoint catalog, and status value semantics. Load this when you need to look up field names, status values, or endpoint behavior.
1---2name: engineering-portfolio-23description: "Portfolio-mix review, SLA aging audit, and release-readiness assessment for an engineering work-item environment exposed through a REST API. Use when a task asks you to classify closed work items into portfolio categories (NewFeature, TechDebt, Reliability, Security), compare actual mix against target mix, audit SLA breaches and overdue aging, assess release readiness against milestones and blockers, or produce structured JSON answers from work-item, release, milestone, blocker, dependency, mix-target, and SLA-policy endpoints. Also use when the task references scope_id-based mix targets, as-of-date SLA windows, release gating, or duplicate/cancelled exclusion logic in an engineering-portfolio context."4license: MIT5compatibility: designed for deepagents-code6metadata:7 source: https://skillmd.com/skills/prism-shadow/engineering-portfolio-28---910# Engineering Portfolio Analysis1112## Overview1314This skill covers three analytical workflows against a shared engineering work-item REST API:15161. **Portfolio Mix Review** — Classify closed work items into four categories (NewFeature, TechDebt, Reliability, Security), compare count-based actual mix against target mix percentages, identify under-invested categories, and recommend a rebalance action.172. **SLA Aging Audit** — Filter primary (non-duplicate, non-cancelled) work items by team and SLA-relevant categories, compute aging buckets relative to an as-of date, identify overdue items against SLA policy by severity, flag duplicate clusters, missing owners, and calculate breach rate.183. **Release Readiness Assessment** — For a specific release, compute milestone completion metrics, identify gating (non-complete) work items, count unresolved high-impact blockers by cause, trace critical dependency chains, and produce a readiness score and ship decision.1920All workflows share a common data model. See [references/data_model.md](references/data_model.md) for the full field reference and API endpoint details.2122## Common Rules for All Workflows2324### Authoritative vs Stale Fields25- The `status` field on each work item is authoritative. Ignore `mirror_status` — it is a stale export snapshot and does not reflect current state.26- The `legacy_category` field is a legacy hint only. Do not use it as the primary classification signal.27- For release-related work, use the work item's `release_id` and `milestone_id` fields, not any mirrored or export-derived fields.2829### Duplicate and Cancelled Handling30- Work items with `status` "Duplicate" must be excluded from primary counts. Their `duplicate_of` field points to the canonical item. Report excluded duplicate IDs separately.31- Work items with `status` "Cancelled" must be excluded from primary counts. Report excluded cancelled IDs separately.32- A Duplicate record may itself have been closed within the scope window. Still exclude it from primary counts regardless of its `closed_at` date.3334### Primary vs Non-Primary Records35- A "primary" work item is one whose `status` is not "Duplicate" and not "Cancelled".36- Primary items are the denominator for all counts, percentages, and rates.37- Duplicate clusters (canonical to duplicates) should be reported as metadata but must not inflate primary counts.3839### Ordering Conventions40- Sort work-item ID lists lexicographically (ASCII sort) unless the task template specifies a different order (e.g. `closed_at` ascending then `id` ascending).41- Sort team lists alphabetically.42- Sort gap/mix table rows in the fixed category order: NewFeature, TechDebt, Reliability, Security.43- Sort duplicate clusters by `primary_id` lexicographically, with `duplicate_ids` within each cluster sorted lexicographically.4445### Numeric Precision46- Percentages derived from counts: divide the category count by the primary total, multiply by 100, round to 1 decimal place (portfolio mix tasks) or 3 decimal places (breach rate, readiness score).47- Gap values: `actual_pct - target_pct`, rounded to the same precision as the percentages.48- When a category has zero items and the total is zero, treat percentages as 0.0.4950## Workflow 1: Portfolio Mix Review5152### Scope Determination531. Read the task prompt for: scope_id, quarter (e.g. 2025-Q4), teams, product area(s), and target scope_id.542. Fetch mix targets from `GET /api/mix-targets` and find the row whose `scope_id` exactly matches the target scope_id from the prompt. This row provides the target percentages: `new_feature_pct`, `tech_debt_pct`, `reliability_pct`, `security_pct`. These are decimals (e.g. 0.34 = 34%); multiply by 100 and round to 1 decimal place for display.553. The quarter defines the closed-date window: a closed work item's `closed_at` must fall within the calendar quarter (e.g. 2025-Q4 = 2025-10-01 through 2025-12-31).5657### Filtering In-Scope Work Items58Fetch all work items from `GET /api/work-items`. Apply these filters:59- `team` matches one of the prompt teams60- `product_area` matches one of the prompt product areas (if specified)61- `closed_at` falls within the quarter window and is not null62- `status` is not "Duplicate" and not "Cancelled"6364Watch for "distractor" records — items that match on team and product_area but use a different data schema (e.g. wrapped in a `work_item` sub-object with `legacy_category` instead of `work_type`). Exclude these from the primary mix and report them separately when the template has an exclusion field for them.6566### Portfolio Category Classification67Assign each included primary work item to exactly one of: NewFeature, TechDebt, Reliability, Security.6869Classification uses a three-signal cascade. Start with the strongest signal and resolve conflicts in order:7071**Signal 1 — `work_type`** (strongest):72- `Security`, `Compliance` to Security73- `Reliability` to Reliability74- `Incident` to Reliability (incident follow-ups represent reliability investment), unless labels are exclusively security (cve/auth/encryption) with no reliability signals75- `Feature` to NewFeature (unless overridden by labels)76- `Enhancement` to check labels; defaults toward Security when no clear feature/reliability signal77- `Refactor`, `Chore`, `Dependency` to TechDebt78- `Bug` to check labels; with reliability labels to Reliability; with security labels to Security; otherwise to TechDebt7980**Signal 2 — `labels`** (secondary):81- Labels containing `security`, `cve`, `encryption` push toward Security82- Labels containing `reliability`, `incident`, `outage`, `latency` push toward Reliability83- Labels containing `cleanup`, `refactor`, `migration`, `dependency` push toward TechDebt84- Labels containing `feature`, `rollout` (without security/reliability override) push toward NewFeature8586**Signal 3 — `title`** (tiebreaker only):87- When work_type and labels conflict or are ambiguous, the title text can break the tie. Keywords: "security", "cve", "encrypt", "auth" to Security; "reliability", "incident", "outage", "latency", "retry", "flaky" to Reliability; "cleanup", "refactor", "migrat" to TechDebt; "feature", "rollout", "enhancement" to NewFeature.8889**Resolution priority**: Security signals dominate Reliability signals dominate TechDebt signals dominate NewFeature. When an item has both security and reliability signals, classify as Security. When it has reliability and tech-debt signals, classify as Reliability. The presence of any security-relevant label (security, cve, encryption) on a Feature or Enhancement work_type overrides the NewFeature default and classifies it as Security.9091### Mix Gap Analysis921. Count items per category to `category_counts`.932. Compute actual percentages: `(count / total_primary) * 100`, rounded to 1 decimal.943. Compare against target percentages from the mix-target row.954. Compute gaps: `actual_pct - target_pct`.965. Identify under-invested categories: those with negative gap, ordered from most negative to least negative.976. Recommend follow-up action:98 - `REBALANCE_CAPACITY` with `rationale_code` `LARGEST_NEGATIVE_GAP` when any gap is negative; set `primary_category` to the most-negative-gap category and `secondary_category` to the second-most-negative (or null if none).99 - `MAINTAIN_CURRENT_MIX` with `rationale_code` `NO_NEGATIVE_GAPS` when no gaps are negative.100 - `INVESTIGATE_DATA_QUALITY` with `rationale_code` `DATA_CONFLICT` when the data has conflicts that prevent a clean recommendation.101102## Workflow 2: SLA Aging Audit103104### Scope Determination1051. Read the task prompt for: teams, SLA-relevant categories (typically Reliability and Security), as-of date, and recent closed window in days.1062. Fetch SLA policy from `GET /api/sla-policy`. This returns an array of `{severity, days_to_due}` objects. Map each severity level to its SLA due window.107108### Filtering In-Scope Work Items109Fetch all work items from `GET /api/work-items`. Apply:110- `team` matches one of the prompt teams111- The item belongs to one of the SLA-relevant categories (classify using the same portfolio category rules as Workflow 1)112- `status` is not "Cancelled" (Duplicate items are excluded from primary but tracked in duplicate clusters)113- `closed_at` is either null (open work) or falls within the recent closed window (closed_at >= as_of_date - window_days)114115### Primary vs Duplicate Separation116- Work items with `status` "Duplicate" form duplicate clusters. Group them by `duplicate_of` (the canonical primary id).117- The canonical primary item must itself be in scope. If a duplicate points to an item outside scope, still report the cluster but do not count the canonical in primary totals.118- All non-Duplicate, non-Cancelled items are primary.119120### SLA Breach Calculation121For each primary item:1221. If `closed_at` is not null, the item is already closed — it is not overdue.1232. If `closed_at` is null, compute age: `as_of_date - created_at` in days.1243. Look up the SLA `days_to_due` for the item's `severity`.1254. If `age > days_to_due`, the item is overdue.126127### Aging Buckets128For each primary item (open or recently closed), compute age from `created_at` to `as_of_date` in days. Bucket into: 0-3, 4-7, 8-14, 15-30, 31+. Count items per bucket.129130### Hotspot and Team Overdue131- Compute overdue counts per team.132- Find the owner/team pair with the most overdue primary items. If multiple tie, use the one with the owner appearing first alphabetically. If owner is missing, use "UNASSIGNED".133- Report `missing_owner_ids`: primary items with null/empty `owner`.134135### Breach Rate136`breach_rate = overdue_primary_count / included_primary_count`, rounded to exactly 3 decimal places.137138### Escalation Queue (when required)139Order overdue primary items by priority for follow-up. Use this precedence: S1 before S2 before S3 before S4. Within the same severity, order by earliest `created_at` first (oldest items first).140141## Workflow 3: Release Readiness Assessment142143### Scope Determination1441. Read the task prompt for the release ID under review.1452. Fetch the release from `GET /api/releases/{release_id}` or from the full list at `GET /api/releases`.1463. Fetch all milestones from `GET /api/milestones`. Filter to those whose `release_id` matches the target release.1474. Fetch all work items, blockers, and dependencies from their respective endpoints.148149### Milestone Completion150For each milestone of the release (sorted by `milestone_id` ascending):1511. Find all work items whose `milestone_id` matches and whose `status` is not "Duplicate" (primary work items).1522. Count completed primary items: those with `status` in the completed set. Treat any of these as completed: `Done`, `Deployed`, `Verified`, `Closed`, `Resolved` (use the exact status strings observed in the API).1533. Compute `completion_pct = (complete_primary / primary_total) * 100`, rounded to 1 decimal.154155### Gating Work Items156Identify non-complete release work items that gate readiness:157- Work items whose `release_id` matches the target release158- `status` is not in the completed set AND not "Duplicate"159- Sort ascending, no duplicates.160161### Blocker Analysis162Fetch blockers from `GET /api/blockers`. Filter for:163- `release_id` matches the target release164- `severity` is "High" or "Critical" (high-impact only)165- `status` is not "Resolved" (unresolved only)166167Count by exact `cause` string. Use the cause text verbatim as the key.168169### Critical Dependency Chains170Fetch all dependencies from `GET /api/dependencies`. For each dependency edge:171- The `blocked_id` is the release work item that is blocked.172- The `depends_on_id` is the work item it depends on.173- The `relation` describes the nature.174175A critical dependency chain exists when: a release work item (has the target `release_id`) is `blocked_id` in a dependency edge, AND the `depends_on_id` work item is itself not complete (status not in completed set).176177Build chains by walking from the blocked release work item. If the dependency is itself blocked by another item (transitive), include the full ordered path: `[blocked_release_item, ..., non_complete_dependency]`. Each link in the chain represents one dependency edge.178179Sort chains lexicographically by the full path (compare the string representation of the path array).180181If no such chains exist, return an empty array.182183### Readiness Score184`readiness_score = total_completed_primary_release_items / total_primary_release_items`, rounded to 3 decimal places.185186Count across all milestones: sum of completed primary items divided by sum of all primary items for the release.187188### Ship Decision189- `SHIP` when readiness_score >= 0.95 AND there are zero unresolved high-impact blockers AND zero gating work items.190- `SHIP_WITH_WATCH` when readiness_score >= 0.80 AND there are zero unresolved high-impact blockers, but there are gating work items.191- `NO_SHIP` when there are unresolved high-impact blockers, OR readiness_score < 0.80, OR there are gating work items of a severity or nature that block release confidence.192193When in doubt between SHIP_WITH_WATCH and NO_SHIP, the presence of any unresolved High or Critical blocker is decisive for NO_SHIP.194195## Resources196197- **[references/data_model.md](references/data_model.md)** — Complete field reference for every API entity, endpoint catalog, and status value semantics. Load this when you need to look up field names, status values, or endpoint behavior.