Engineering Portfolio Management
Analyze engineering work-item portfolios against an environment API. The API exposes work items, mix targets, SLA policy, releases, milestones, blockers, and dependencies through REST endpoints and supports a restricted SQL query endpoint.
Task Types
Three core task types appear in this domain. Read the user's prompt to identify which is being asked.
1. Portfolio Mix Review
Classify closed work items into four portfolio categories, compare against target mix percentages, and produce rebalancing recommendations.
2. SLA Aging Audit
Identify primary SLA-relevant work items, determine overdue status against SLA policy, compute breach rate, and surface hotspots, missing owners, and duplicate clusters.
3. Release Readiness Assessment
Evaluate a release using milestone data, work-item statuses, blockers, and dependencies. Produce a ship decision, readiness score, and gating-item list.
API Reference
The environment base URL is provided as <TASK_ENV_BASE_URL> in the user
prompt. The runtime-access notes (typically environment_access.md) list the
available endpoints and any token needed for SQL queries.
REST Endpoints
GET /api/work-items— list all work itemsGET /api/work-items/{item_id}— single work itemGET /api/mix-targets— all mix target rowsGET /api/sla-policy— SLA severity-to-days mappingGET /api/releases— all releasesGET /api/releases/{release_id}— single release with its milestones and blockersGET /api/milestones— all milestonesGET /api/dependencies— all dependency recordsGET /api/blockers— all blocker recordsPOST /api/query— restricted SQL endpoint (may requireX-Env-Tokenheader)
Work-Item Schema
{
"id": "WI-24024-P001",
"title": "...",
"status": "Closed | Verified | Done | Deployed | Review | In Progress | Backlog | Duplicate | Cancelled | ...",
"work_type": "Feature | Enhancement | Refactor | Bug | Chore | Dependency | Security | Reliability | Incident | Compliance",
"labels": ["array", "of", "strings"],
"legacy_category": "bug | new | security | tech-debt | maintenance | quality | admin | incident | ...",
"mirror_status": "Closed | Open | Done | In Progress | Blocked | ... (UNRELIABLE - IGNORE THIS FIELD)",
"team": "string",
"product_area": "string",
"owner": "string or null",
"priority": "integer 1-5",
"severity": "S1 | S2 | S3 | S4",
"story_points": "integer",
"created_at": "YYYY-MM-DD",
"due_at": "YYYY-MM-DD",
"closed_at": "YYYY-MM-DD | null",
"duplicate_of": "string work-item id or null",
"release_id": "string or null",
"milestone_id": "string or null"
}
Mix-Target Schema
{
"scope_id": "string",
"quarter": "string",
"team_group": "string",
"product_area": "string",
"new_feature_pct": "float (fraction, multiply by 100 for percentage points)",
"tech_debt_pct": "float",
"reliability_pct": "float",
"security_pct": "float"
}
SLA Policy Schema
{
"severity": "S1",
"days_to_due": 3
}
The policy array has four entries: S1 (3 days), S2 (10 days), S3 (21 days), S4 (45 days).
Release Schema (from /api/releases/{release_id})
Returns a release object plus arrays of milestones and blockers for that
release.
Milestone Schema
{
"id": "MIL-...",
"name": "string",
"owner_team": "string",
"release_id": "string"
}
Blocker Schema
{
"id": "BLK-...",
"cause": "string",
"severity": "Low | Medium | High | Critical",
"status": "Open | Monitoring | Resolved",
"work_item_id": "string",
"release_id": "string"
}
Dependency Schema
{
"blocked_id": "string",
"depends_on_id": "string",
"relation": "depends-on | blocks-release-readiness | validation-required | ..."
}
Core Workflow
All three task types follow this general approach:
- Fetch data from the environment API endpoints relevant to the task.
- Filter to the task's scope (teams, product areas, quarter, release, as-of date).
- Classify each included work item, excluding Duplicate/Cancelled records and identifying distractor records.
- Compute the required metrics (percentages, gaps, breach rates, readiness scores).
- Return the answer JSON matching the provided answer template.
Step-by-Step API Data Gathering
Always start by fetching the primary collection:
GET /api/work-itemsto get all work items.- Depending on the task type, also fetch:
- Mix review:
GET /api/mix-targets - SLA audit:
GET /api/sla-policy - Release assessment:
GET /api/releases/{release_id}(provides release, milestones, and blockers in one call), thenGET /api/dependenciesfor dependency records
- Mix review:
You may also inspect individual work items with GET /api/work-items/{item_id} when you need to double-check data for specific
items. Batch reading the full work-items list is preferred over individual
fetches.
Authoritative Field Resolution
The environment has stale or legacy fields that must not be used as truth:
statusis authoritative for work state.mirror_statusis stale and must always be ignored.work_typeandlabelsare authoritative for classification.legacy_categoryis a weaker fallback only.severityis authoritative for SLA severity.due_atis authoritative for SLA due-date calculations.closed_atis authoritative for when an item was closed.duplicate_ofpoints to the primary/canonical work item. When an item hasstatus: "Duplicate"and aduplicate_ofvalue, theduplicate_ofitem is the primary. When an item hasstatus: "Closed"butduplicate_ofis non-null, treat it as an effective duplicate that should be excluded.
Inclusion Rules (All Task Types)
A work item is included as primary when:
- It matches the task scope (teams, product areas, quarter/release, categories).
- Its
statusis NOT "Duplicate" and NOT "Cancelled". - It is not a distractor record (stale mirror, wrong scope, stale-export artifact).
A work item is excluded when:
statusis "Duplicate" — flag as excluded (duplicate), note theduplicate_ofpointer.statusis "Cancelled" — flag as excluded (cancelled).- It is in scope but is a stale-mirror record, legacy-export artifact, or
otherwise not a genuine primary work record. Items with labels like
stale-exportor withstatus: "Closed"butduplicate_ofpointing at a primary should be treated as duplicates rather than primaries.
Ordering Conventions
Apply these ordering rules consistently across all answer outputs:
- Work-item ID lists: sort lexicographically (standard string sort, e.g.,
Python
sorted()with default string comparison). - Team lists: sort alphabetically.
- Duplicate clusters: sort by
primary_idascending, withduplicate_idssorted lexicographically within each cluster. - Milestone lists: sort by
milestone_idascending. - Gap table rows: present in fixed category order: NewFeature, TechDebt, Reliability, Security.
- Under-invested categories: order from most negative gap to least negative gap.
- Escalation queue: order by severity S1 first, then
due_atascending within each severity tier.
Task 1: Portfolio Mix Review
Scope Identification
Extract from the user prompt:
scope_id— the identifier for this analysisquarter— e.g., "2025-Q4"teams— the list of team names in scopeproduct_areas— the list of product areas in scope (may be a single product area or multiple)- Target mix: find the
mix_targetsrow wherescope_idmatches the given scope id
Work-Item Filtering
From all work items, select those where:
teamis in the scope teams listproduct_areais in the scope product areas listclosed_atfalls within the scope quarter (for Q4 2025: months 10, 11, 12)statusis NOT "Duplicate" and NOT "Cancelled"
Portfolio Category Classification
Classify each included work item into exactly one of: NewFeature, TechDebt, Reliability, Security.
Use this priority-ranked resolution rule to resolve conflicting signals:
Security — when any of these is true:
work_typeis "Security" or "Compliance"labelscontainsecurity,cve,auth, orencryptionlegacy_categoryis "security"- When
work_typeis "Feature", "Enhancement", or "Dependency" and labels or legacy_category point to security
Reliability — when any of these is true:
work_typeis "Reliability" or "Incident"labelscontainreliability,outage,incident,latency, orflakylegacy_categoryis "incident"
TechDebt — when any of these is true:
work_typeis "Refactor", "Bug", "Chore", or "Dependency"legacy_categoryis "tech-debt", "bug", "maintenance", "admin", or "cleanup"work_typeis "Feature" or "Enhancement" but labels includemigrationorcleanup(indicating maintenance work rather than new features)
NewFeature — when:
work_typeis "Feature" or "Enhancement" AND no stronger signal pushes it into another categorylegacy_categoryis "new" AND no contradictory label or work_type signal exists
Tie-breaking: When multiple signals point to different categories, resolve
by evidence weight: a matching work_type or labels signal beats a matching
legacy_category. When signals are equally specific, prefer the one that best
describes the work's primary nature. If still ambiguous, read the item's
title for context.
A signal is stronger when it is more specific. For example, work_type: "Security" is unambiguous and should dominate any label or legacy signal.
labels: ["security"] is strong but could be stale; cross-check with
work_type and legacy_category. legacy_category: "security" alone is the
weakest security signal and should only classify an item as Security when
work_type and labels are silent or ambiguous.
Identifying Distractors and Exclusions
In addition to Duplicate and Cancelled items, identify distractor records that should be excluded:
- Items whose
duplicate_ofpoints at a primary item even if their ownstatusis not "Duplicate" (check for items Closed but withduplicate_ofset, where the Closed status may be stale). - Items with labels like
stale-exportthat indicate they are mirror artifacts. - Items that match the scope teams/product_areas but have
closed_atoutside the quarter.
For each excluded item, determine the exclusion reason: duplicate, cancelled, or distractor.
Computing the Mix
- Count items per category to produce
category_counts. - Compute
category_percentages: (count_in_category / total_included) * 100, rounded to 1 decimal place. - Build
gap_table: for each category in order NewFeature, TechDebt, Reliability, Security:target_pctfrom the mix-targets row (multiply by 100: e.g., 0.34 becomes 34.0)actual_pctfrom step 2gap_pct=actual_pct - target_pct, rounded to 1 decimal place
- Identify
under_invested_categories: categories with negativegap_pct, sorted from most negative to least. - Determine recommended action:
- If there are negative gaps: action = REBALANCE_CAPACITY, primary_category = the most under-invested category, secondary_category = the second most under-invested (or null if only one), rationale_code = LARGEST_NEGATIVE_GAP
- If all gaps are non-negative: action = MAINTAIN_CURRENT_MIX, primary_category = null, secondary_category = null, rationale_code = NO_NEGATIVE_GAPS
Ordering
included_work_item_ids: sorted byclosed_atascending, then byidascending for ties.excluded_*_ids: sorted byclosed_atascending, then byidascending.
Task 2: SLA Aging Audit
Scope Identification
Extract from the user prompt:
teams— the list of team namesas_ofdate — the date for aging calculationsrecent_closed_window_days— items closed within this many days beforeas_ofare still considered recent closures, not overduecategoriesorsla_categories— e.g., ["Security", "Reliability"]
Work-Item Classification for SLA
An item is SLA-relevant if its portfolio category (as determined by the Task 1 classification rules above) matches one of the specified SLA categories.
For SLA-specific tasks that only ask about Reliability and Security, use the same classification rules narrowed to those two categories: any item that would classify as Reliability or Security under the full rules is included.
Identifying Primary vs. Duplicate
- If
statusis "Duplicate" andduplicate_ofis set: the item is a duplicate. Theduplicate_ofitem is the primary. - If
statusis "Duplicate" butduplicate_ofis null: treat as an anomalous record; exclude from primary set. - Items with
status"Cancelled" are excluded from the primary set.
Build duplicate_clusters: for each primary that has one or more duplicates
pointing at it, list the primary_id and the sorted duplicate_ids. Include
clusters even when the primary id itself is in the primary set (the duplicate
should still be reported). Sort clusters by primary_id.
SLA Overdue Calculation
- Parse
due_atandas_ofas dates using Python'sdatetime.dateordatetime.fromisoformat. - Compute aging days:
aging_days = (as_of - due_at).days. Ifas_ofis beforedue_at,aging_daysis negative and the item is not yet due. - Look up the SLA policy from
GET /api/sla-policy. Map severity todays_to_due:- S1: 3 days
- S2: 10 days
- S3: 21 days
- S4: 45 days
- An item is overdue when
aging_days > sla_policy[severity].days_to_dueAND the item has not been recently closed. - Recent closure check: if an item's
closed_atis not null and(as_of - closed_at).days <= recent_closed_window_days, the item was recently closed and is NOT overdue, regardless of aging days.
Aging Buckets
Distribute included primary items into aging buckets based on aging_days = (as_of - due_at).days:
- 0-3: 0 <= aging_days <= 3
- 4-7: 4 <= aging_days <= 7
- 8-14: 8 <= aging_days <= 14
- 15-30: 15 <= aging_days <= 30
- 31+: aging_days >= 31
Count items in each bucket. If aging_days is negative (item not yet due), place in the 0-3 bucket (or 0 depending on convention — follow the answer template's field definitions).
Team Overdue Counts
For each team in scope, count the number of included primary items that are overdue. List teams alphabetically.
Top Hotspot
Find the owner/team pair with the most overdue primary records. If there's a tie, choose the pair with the highest-severity overdue items (most S1 items first, then S2, etc.). Report:
team: the team nameowner: the owner name, or "UNASSIGNED" when owner is null/missingoverdue_count: the count
Missing Owner IDs
List all included primary ids where owner is null/null-like. Sort
lexicographically.
Breach Rate
breach_rate = len(overdue_primary_ids) / len(included_primary_ids), rounded
to exactly 3 decimal places. Use Python's round(breach_rate, 3).
Escalation Queue (when required)
Order overdue primary ids by priority for escalation:
- Highest severity first (S1, then S2, then S3, then S4)
- Within same severity: earliest
due_atfirst (oldest due date is most urgent) - Within same due_at: lexicographic by id
Overdue Counts by Severity (when required)
Count overdue primary items grouped by severity tier (S1, S2, S3, S4). Each count is an integer.
Task 3: Release Readiness Assessment
Scope Identification
Extract the release_id from the user prompt.
Data Gathering
GET /api/releases/{release_id}— returns the release object, its milestones, and its blockers in a single response.GET /api/dependencies— all dependency records (filter to those involving the release's work items).GET /api/work-items— all work items (filter to those withrelease_idmatching the target release).
Work-Item Filtering
Identify all work items where release_id matches the target release. These
are the release's primary work items. Treat every such work item as primary
unless its status is "Duplicate" or "Cancelled".
Milestone Completion
For each milestone associated with the release:
complete_primary: count of primary work items in this milestone withstatusin {"Done", "Verified", "Deployed", "Closed"} (any status indicating completion).primary_total: total primary work items in this milestone.completion_pct: (complete_primary / primary_total) * 100, rounded to 1 decimal place. Ifprimary_totalis 0, use 0.0.
Sort the milestone_completion array by milestone_id ascending.
Ship Decision
Determine the ship decision using this logic:
- SHIP: All milestones have
completion_pct >= 100.0AND there are no unresolved blockers with severity "High" or "Critical" for this release. - SHIP_WITH_WATCH: At least one milestone has
completion_pct >= 100.0AND the average completion across all milestones is >= 70.0%, AND there are no unresolved blockers with severity "Critical". May have unresolved "High"-severity blockers. - NO_SHIP: Otherwise — incomplete milestones with low completion, unresolved "Critical" blockers, or a combination that prevents ship.
"Unresolved" blockers have status NOT "Resolved" (i.e., "Open" or
"Monitoring").
Gating Work Items
List all primary work items for the release that are NOT in a completed state.
A work item is "complete" when its status is "Done", "Verified", "Deployed",
or "Closed". Sort the list lexicographically with no duplicates.
Unresolved High-Impact Blocker Causes
Count blockers for the release where:
severityis "High" or "Critical"statusis NOT "Resolved" (i.e., "Open" or "Monitoring")
Group by exact cause text. Key the counts by the cause string exactly as it
appears in the API.
The data is most reliably read from the per-release endpoint (GET /api/releases/{release_id}) which returns blockers already scoped to the
release.
Critical Dependency Chains
A critical dependency chain exists when:
- A non-complete release work item (
blocked_id) appears in a dependency record - The
depends_on_idwork item is also non-complete
Build chains as ordered paths: [blocked_id, depends_on_id]. If the
dependency's depends_on_id itself appears as a blocked_id in another
dependency record whose target is also non-complete, extend the chain.
Sort chains lexicographically by the full path (compare first element, then second, etc.).
If there are no critical dependency chains, return [].
Readiness Score
readiness_score = total_completed_primary / total_primary, rounded to 3
decimal places.
Where "completed" means status in {"Done", "Verified", "Deployed", "Closed"}
and "total_primary" is the count of all non-Duplicate, non-Cancelled release
work items.
Common Pitfalls
Mirror Field Confusion:
mirror_statusis stale. Never use it. Always readstatusfor the real work state.Legacy Category Overreliance:
legacy_categoryis a weak fallback. Usework_typeandlabelsas primary classification signals. Only fall back tolegacy_categorywhenwork_typeandlabelsare silent.Duplicate Handling: When
statusis "Duplicate", the item must be excluded from primary counts. Theduplicate_ofpointer identifies the primary item — make sure that primary item itself is included if it meets scope criteria. An item that is "Closed" but hasduplicate_ofset is effectively a duplicate.Date Arithmetic: When computing aging, use proper date subtraction.
aging_days = (as_of - due_at).daysusing Python'sdatetime. Ifclosed_atis null,aging_days=(as_of - due_at).daysdirectly.Percentage Rounding: Mix percentages to 1 decimal place. Breach rates and readiness scores to 3 decimal places. Use Python's built-in
round()function.Gap Table Order: Always present categories in the fixed order: NewFeature, TechDebt, Reliability, Security — regardless of what order the API data uses.
Sort Stability: For ID lists, use lexicographic string sort. Do not sort by numeric substring, do not strip the prefix. "WI-24024-007" sorts before "WI-24024-012" and "WI-24024-P001" sorts after both because "P" > "0" in ASCII/Unicode string comparison.
Closed-at Window for SLA: In SLA audits, items with
closed_atwithin the recent window ofas_ofare not overdue. Checkclosed_atbefore computing overdue status.Escalation Queue Ordering: Priority is severity first (S1 > S2 > S3 > S4), then
due_atascending within the same severity.Scope Precision for Quarters: For portfolio mix reviews with quarter scoping, only count items whose
closed_atfalls within that quarter's months. For Q4 2025: months 10, 11, 12 (October through December). Checkclosed_at[:7]or parse the date.Distractor Identification: Items that match scope teams/areas but have stale labels, wrong quarters, or are mirror artifacts must be excluded and listed separately. Look for labels like
stale-export, or items whoseduplicate_offield reveals they are not genuine primaries.Percentages Sum Check: After computing mix percentages, verify that the four category percentages sum to approximately 100.0 (allow 0.2 tolerance for rounding). If they deviate significantly, recheck your counts.
Answer Template Adherence
The user provides an answer template (answer_template.json or equivalent
schema). Your output must follow it exactly — every required field present, no
extra fields, enum values matching the allowed set, types matching the schema
constraints.
Before returning the final JSON:
- Verify all required fields are present.
- Check that enum values match the allowed set.
- Verify counts sum correctly to the total included.
- Verify percentages sum to approximately 100% (allow for 0.2 rounding tolerance).
- Verify sorting conventions are followed.
- Double-check that Duplicate and Cancelled items are excluded from primary counts and listed in the exclusion fields.
Return only the JSON object. Do not include prose, markdown fences, or commentary outside the JSON unless the answer template explicitly allows prose fields.
See references/classification-guide.md for worked examples of the portfolio classification rules across the five training scenarios.