Engineering Portfolio Review
Overview
Analyse work-tracking data from the task environment API to produce portfolio mix
reviews, SLA aging audits, and release readiness assessments. The environment
exposes REST endpoints for work items, mix targets, SLA policy, releases,
milestones, dependencies, and blockers. The data contains deliberate distractor
signals (stale mirror fields, legacy categories, duplicate records, cancelled
items) that must be handled with explicit exclusion and classification rules.
Quick Start
Fetch environment data with the bundled query script:
TASK_ENV_BASE_URL=http://task-env:9024 python scripts/query_env.py work-items
All endpoints share a common base URL provided in the task prompt. No
authentication is required for the standard GET endpoints. The SQL query
endpoint (POST /api/query) may require a token supplied in
environment_access.md.
Available endpoints: /api/work-items, /api/work-items/{id},
/api/mix-targets, /api/sla-policy, /api/releases, /api/releases/{id},
/api/milestones, /api/dependencies, /api/blockers, /api/query.
Portfolio Category Classification
Every included work item must be classified into exactly one of four categories:
NewFeature, TechDebt, Reliability, Security. Use the priority
chain below. See references/classification.md
for the full label-to-category mapping and worked examples.
Classification Priority Chain
- Labels (strongest signal). Scan the
labels array for category keywords.
When multiple category signals are present, resolve with this priority:
Security > Reliability > TechDebt > NewFeature.
- Work type (
work_type field). Used when labels produce no clear signal.
- Legacy category (
legacy_category field). Used as a tiebreaker when
labels and work_type are ambiguous. Never use as a primary signal.
- Title keywords. Final tiebreaker. Scan the
title string for
category-signal substrings.
Special Signal Handling
- Stale markers: When a title contains "stale" next to a category keyword
(e.g. "stale security label"), the referenced classification signal is
unreliable. Deprioritise that signal and rely on remaining signals.
stale-export label: Treat as noise. A stale-export label does not
contribute to any category signal. Rely on other labels and fields.
mirror_status field: Always ignore. Use status as the authoritative
state. The mirror_status field is a stale export artefact.
legacy_category field: Never use as the primary classification signal.
Use only as a tiebreaker when signals from labels and work_type are
ambiguous or absent.
Classification Examples
| Labels |
Work Type |
Legacy |
Title |
Result |
[feature, rollout, security] |
Feature |
security |
"...stale security label..." |
Security — the security label is present; the title's "stale" descriptor flags a stale label but the label is genuinely a security signal |
[auth, encryption, cleanup, refactor] |
Refactor |
tech-debt |
— |
TechDebt — labels are ambiguous (auth/encryption suggest Security, refactor suggests TechDebt); legacy tiebreaker resolves to TechDebt |
[reliability, latency, flaky] |
Bug |
quality |
— |
Reliability — labels are unambiguous reliability signals |
[feature, rollout] |
Enhancement |
security |
— |
Security — no label signal; legacy tiebreaker tips to security |
[cleanup, flaky, reliability] |
Chore |
quality |
"queue cleanup for flaky reliability alert" |
Reliability — labels have a clear reliability signal |
[migration, cleanup, auth] |
Dependency |
security |
— |
Security — auth label + security legacy agree |
[outage, reliability, feature] |
Enhancement |
new |
— |
Reliability — labels provide a reliability signal |
Exclusion Rules
Before counting or including a work item, apply these exclusion checks in order:
- Cancelled:
status == "Cancelled" -> exclude entirely. Record the ID as
an excluded cancelled item but do not count it in any category.
- Duplicate:
status == "Duplicate" or duplicate_of is non-null ->
exclude from primary counts. Record the ID and its duplicate_of reference
for the duplicate-cluster report. The referenced primary item stays in the
primary set unless it is also excluded by another rule.
- Out-of-scope date/quarter: Only include items whose
closed_at falls
within the scope date range or quarter. Items with closed_at: null are
never included in closed-portfolio analysis.
- Scope mismatch: Filter by the specified
team and product_area values
from the task scope.
SLA Aging
See references/sla-aging.md for full methodology,
aging bucket definitions, and escalation ordering rules.
Quick SLA Rules
- The SLA policy endpoint returns a severity-to-
days_to_due map.
- An item is overdue when
created_at + days_to_due < as_of and the item
is not yet closed (closed_at is null or after as_of).
- The recent closed window covers items closed within N days before
as_of. These are not overdue even if they were past due at close.
- Aging buckets: Compute
(as_of - created_at).days for every open primary
item. Bucket into 0-3, 4-7, 8-14, 15-30, 31+ days.
- SLA breach rate =
len(overdue_primary_ids) / len(included_primary_ids),
rounded to 3 decimal places.
- Escalation order: Sort overdue items by severity (S1 first), then by age
descending within the same severity tier.
Release Readiness
See references/release-readiness.md for the
complete workflow.
Quick Release Rules
- Fetch the release, its milestones, and all work items assigned to those
milestones.
- Primary work: exclude Duplicate/Cancelled items per the standard exclusion
rules.
- Milestone completion:
complete_primary / primary_total per milestone.
An item is complete when status is in {Verified, Deployed, Done, Closed}.
- Gating work items: non-complete primary release work items that have
open high-severity blockers or unresolved critical dependencies.
- High-impact blockers: blockers with
severity in {Critical, High} and
status != "Resolved".
- Ship decision:
NO_SHIP when any high-impact blockers exist or any milestone is below
a completion threshold.
SHIP_WITH_WATCH when all milestones meet minimum thresholds but minor
issues remain.
SHIP when all milestones are fully complete with no open blockers.
- Readiness score =
completed_primary / total_primary, rounded to 3
decimal places.
Portfolio Mix Analysis
Mix Targets
Fetch /api/mix-targets and locate the row matching the task's scope_id.
Extract new_feature_pct, tech_debt_pct, reliability_pct, and
security_pct. These are decimal values (e.g. 0.34 = 34.0%). Convert to
percentage points by multiplying by 100 and rounding to 1 decimal place.
Actual Mix
After classifying every included work item (see Classification section),
compute category counts and percentage shares:
actual_pct = round((category_count / total_included) * 100, 1)
gap_pct = round(actual_pct - target_pct, 1)
Gap Analysis
- Under-invested categories: categories with
gap_pct < 0, sorted from
most negative to least negative.
- Largest deficit: the single category with the most negative
gap_pct.
- Recommended action:
REBALANCE_CAPACITY toward the largest deficit
category. Assign the owner team that has the most included work in that
category, or the team with the largest overall share of included work.
Output Ordering Conventions
- Work item ID lists: sort lexicographically (ascending) unless the task
specifies
closed_at ascending then ID ascending.
- Team lists: sort alphabetically.
- Category tables: always order as NewFeature, TechDebt, Reliability, Security.
- Duplicate clusters: sort by
primary_id ascending; duplicate_ids ascending
within each cluster.
- Percentages: round to 1 decimal place (portfolio) or 3 decimal places (SLA
breach rate, readiness score).
Scripts
scripts/query_env.py — Fetch data from any task
environment API endpoint. Supports all listed GET endpoints and POST
/api/query.
References
references/classification.md — Full
label-to-category mapping, edge cases, and worked examples.
references/sla-aging.md — SLA overdue
calculation, aging buckets, escalation queue, and breach rate methodology.
references/release-readiness.md —
Release readiness workflow, milestone completion, blocker analysis,
dependency chains, and ship decision logic.
1---2name: eng-portfolio-review-33description: "Engineering portfolio intelligence for mixed work-tracking environments. Use when preparing portfolio mix reviews, SLA aging audits, release readiness assessments, or any analysis of work items across teams and product areas. Handles: (1) portfolio category classification of work items into NewFeature, TechDebt, Reliability, and Security, (2) target-vs-actual mix gap analysis, (3) SLA overdue and aging bucket calculations with severity-based policies, (4) release readiness scoring from milestone completion, blocker, and dependency data, (5) detection and exclusion of duplicates, cancelled items, stale mirror fields, and legacy category signals. Trigger on phrases like 'portfolio mix review', 'SLA aging audit', 'release readiness assessment', 'closed work portfolio', 'engineering portfolio', 'mix target analysis', or when working with work item data from the shared task environment API."4license: MIT5compatibility: designed for deepagents-code6metadata:7 source: https://skillmd.com/skills/prism-shadow/eng-portfolio-review-38---910# Engineering Portfolio Review1112## Overview1314Analyse work-tracking data from the task environment API to produce portfolio mix15reviews, SLA aging audits, and release readiness assessments. The environment16exposes REST endpoints for work items, mix targets, SLA policy, releases,17milestones, dependencies, and blockers. The data contains deliberate distractor18signals (stale mirror fields, legacy categories, duplicate records, cancelled19items) that must be handled with explicit exclusion and classification rules.2021## Quick Start2223Fetch environment data with the bundled query script:2425```bash26TASK_ENV_BASE_URL=http://task-env:9024 python scripts/query_env.py work-items27```2829All endpoints share a common base URL provided in the task prompt. No30authentication is required for the standard GET endpoints. The SQL query31endpoint (`POST /api/query`) may require a token supplied in32`environment_access.md`.3334Available endpoints: `/api/work-items`, `/api/work-items/{id}`,35`/api/mix-targets`, `/api/sla-policy`, `/api/releases`, `/api/releases/{id}`,36`/api/milestones`, `/api/dependencies`, `/api/blockers`, `/api/query`.3738## Portfolio Category Classification3940Every included work item must be classified into exactly one of four categories:41**NewFeature**, **TechDebt**, **Reliability**, **Security**. Use the priority42chain below. See [references/classification.md](references/classification.md)43for the full label-to-category mapping and worked examples.4445### Classification Priority Chain46471. **Labels** (strongest signal). Scan the `labels` array for category keywords.48 When multiple category signals are present, resolve with this priority:49 Security > Reliability > TechDebt > NewFeature.502. **Work type** (`work_type` field). Used when labels produce no clear signal.513. **Legacy category** (`legacy_category` field). Used as a tiebreaker when52 labels and work_type are ambiguous. Never use as a primary signal.534. **Title keywords**. Final tiebreaker. Scan the `title` string for54 category-signal substrings.5556### Special Signal Handling5758- **Stale markers**: When a title contains "stale" next to a category keyword59 (e.g. "stale security label"), the referenced classification signal is60 unreliable. Deprioritise that signal and rely on remaining signals.61- **`stale-export` label**: Treat as noise. A `stale-export` label does not62 contribute to any category signal. Rely on other labels and fields.63- **`mirror_status` field**: Always ignore. Use `status` as the authoritative64 state. The `mirror_status` field is a stale export artefact.65- **`legacy_category` field**: Never use as the primary classification signal.66 Use only as a tiebreaker when signals from labels and work_type are67 ambiguous or absent.6869### Classification Examples7071| Labels | Work Type | Legacy | Title | Result |72|--------|-----------|--------|-------|--------|73| `[feature, rollout, security]` | Feature | security | "...stale security label..." | **Security** — the security label is present; the title's "stale" descriptor flags a stale *label* but the label is genuinely a security signal |74| `[auth, encryption, cleanup, refactor]` | Refactor | tech-debt | — | **TechDebt** — labels are ambiguous (auth/encryption suggest Security, refactor suggests TechDebt); legacy tiebreaker resolves to TechDebt |75| `[reliability, latency, flaky]` | Bug | quality | — | **Reliability** — labels are unambiguous reliability signals |76| `[feature, rollout]` | Enhancement | security | — | **Security** — no label signal; legacy tiebreaker tips to security |77| `[cleanup, flaky, reliability]` | Chore | quality | "queue cleanup for flaky reliability alert" | **Reliability** — labels have a clear reliability signal |78| `[migration, cleanup, auth]` | Dependency | security | — | **Security** — auth label + security legacy agree |79| `[outage, reliability, feature]` | Enhancement | new | — | **Reliability** — labels provide a reliability signal |8081## Exclusion Rules8283Before counting or including a work item, apply these exclusion checks in order:84851. **Cancelled**: `status == "Cancelled"` -> exclude entirely. Record the ID as86 an excluded cancelled item but do not count it in any category.872. **Duplicate**: `status == "Duplicate"` or `duplicate_of` is non-null ->88 exclude from primary counts. Record the ID and its `duplicate_of` reference89 for the duplicate-cluster report. The referenced primary item stays in the90 primary set unless it is also excluded by another rule.913. **Out-of-scope date/quarter**: Only include items whose `closed_at` falls92 within the scope date range or quarter. Items with `closed_at: null` are93 never included in closed-portfolio analysis.944. **Scope mismatch**: Filter by the specified `team` and `product_area` values95 from the task scope.9697## SLA Aging9899See [references/sla-aging.md](references/sla-aging.md) for full methodology,100aging bucket definitions, and escalation ordering rules.101102### Quick SLA Rules103104- The SLA policy endpoint returns a severity-to-`days_to_due` map.105- An item is **overdue** when `created_at + days_to_due < as_of` and the item106 is not yet closed (`closed_at` is null or after `as_of`).107- The **recent closed window** covers items closed within N days before108 `as_of`. These are not overdue even if they were past due at close.109- **Aging buckets**: Compute `(as_of - created_at).days` for every open primary110 item. Bucket into 0-3, 4-7, 8-14, 15-30, 31+ days.111- **SLA breach rate** = `len(overdue_primary_ids) / len(included_primary_ids)`,112 rounded to 3 decimal places.113- **Escalation order**: Sort overdue items by severity (S1 first), then by age114 descending within the same severity tier.115116## Release Readiness117118See [references/release-readiness.md](references/release-readiness.md) for the119complete workflow.120121### Quick Release Rules122123- Fetch the release, its milestones, and all work items assigned to those124 milestones.125- **Primary work**: exclude Duplicate/Cancelled items per the standard exclusion126 rules.127- **Milestone completion**: `complete_primary / primary_total` per milestone.128 An item is complete when `status` is in {Verified, Deployed, Done, Closed}.129- **Gating work items**: non-complete primary release work items that have130 open high-severity blockers or unresolved critical dependencies.131- **High-impact blockers**: blockers with `severity` in {Critical, High} and132 `status != "Resolved"`.133- **Ship decision**:134 - `NO_SHIP` when any high-impact blockers exist or any milestone is below135 a completion threshold.136 - `SHIP_WITH_WATCH` when all milestones meet minimum thresholds but minor137 issues remain.138 - `SHIP` when all milestones are fully complete with no open blockers.139- **Readiness score** = `completed_primary / total_primary`, rounded to 3140 decimal places.141142## Portfolio Mix Analysis143144### Mix Targets145146Fetch `/api/mix-targets` and locate the row matching the task's `scope_id`.147Extract `new_feature_pct`, `tech_debt_pct`, `reliability_pct`, and148`security_pct`. These are decimal values (e.g. 0.34 = 34.0%). Convert to149percentage points by multiplying by 100 and rounding to 1 decimal place.150151### Actual Mix152153After classifying every included work item (see Classification section),154compute category counts and percentage shares:155156```157actual_pct = round((category_count / total_included) * 100, 1)158gap_pct = round(actual_pct - target_pct, 1)159```160161### Gap Analysis162163- **Under-invested categories**: categories with `gap_pct < 0`, sorted from164 most negative to least negative.165- **Largest deficit**: the single category with the most negative `gap_pct`.166- **Recommended action**: `REBALANCE_CAPACITY` toward the largest deficit167 category. Assign the owner team that has the most included work in that168 category, or the team with the largest overall share of included work.169170## Output Ordering Conventions171172- Work item ID lists: sort lexicographically (ascending) unless the task173 specifies `closed_at` ascending then ID ascending.174- Team lists: sort alphabetically.175- Category tables: always order as NewFeature, TechDebt, Reliability, Security.176- Duplicate clusters: sort by `primary_id` ascending; `duplicate_ids` ascending177 within each cluster.178- Percentages: round to 1 decimal place (portfolio) or 3 decimal places (SLA179 breach rate, readiness score).180181## Scripts182183- [`scripts/query_env.py`](scripts/query_env.py) — Fetch data from any task184 environment API endpoint. Supports all listed GET endpoints and POST185 `/api/query`.186187## References188189- [`references/classification.md`](references/classification.md) — Full190 label-to-category mapping, edge cases, and worked examples.191- [`references/sla-aging.md`](references/sla-aging.md) — SLA overdue192 calculation, aging buckets, escalation queue, and breach rate methodology.193- [`references/release-readiness.md`](references/release-readiness.md) —194 Release readiness workflow, milestone completion, blocker analysis,195 dependency chains, and ship decision logic.