Engineering Portfolio Environment
Core Workflow
- Read the user prompt,
environment_access.md, and the answer template before querying data. - Use the base URL and token exactly as supplied by
environment_access.md; never call/api/judge. - Fetch authoritative records through the business endpoints or
POST /api/query. - Build the answer from source-of-truth fields, then validate it against the template shape.
- Return only the requested JSON when the prompt says not to include prose.
Useful endpoint set:
GET /api/work-itemsGET /api/work-items/{item_id}GET /api/mix-targetsGET /api/sla-policyGET /api/releasesGET /api/releases/{release_id}GET /api/milestonesGET /api/dependenciesGET /api/blockersPOST /api/querywith{"sql":"SELECT ...","params":[]}and the required token header
Prefer SQL for scoped joins and reproducible filtering. Use only SELECT or WITH statements.
Source-Of-Truth Rules
- Trust
status,closed_at,created_at,due_at,work_type,labels,title,team,product_area,release_id,milestone_id,duplicate_of,severity,priority, andowner. - Treat
mirror_statusandlegacy_categoryas stale export fields. Do not use them to decide current status, completion, inclusion, or category when authoritative fields disagree. - Treat a record as duplicate when
duplicate_ofis non-null orstatusisDuplicate. Exclude duplicates from primary denominators and report them only in duplicate fields when requested. - Treat
status: Cancelledas non-primary. Exclude it from primary denominators and report it only in cancelled/distractor fields when requested. - Treat complete primary statuses as
Closed,Done,Verified, andDeployed. Treat all other non-duplicate, non-cancelled statuses as non-complete unless the prompt defines a different rule. - Parse
labelsas a list, not as an opaque string. - Use item counts for portfolio mix unless the prompt explicitly asks for story points.
Category Resolution
Classify each primary work item into exactly one portfolio category. Resolve conflicting signals in this priority order:
Security:work_typeisSecurityorCompliance, or labels/title contain security-specific terms such assecurity,cve,auth,encryption, orcompliance.Reliability:work_typeisReliability,Incident, orBug, or labels/title contain reliability terms such asreliability,incident,outage,latency,flaky, orretry.TechDebt:work_typeisRefactor,Chore, orDependency, or labels/title contain debt terms such ascleanup,refactor,migration,deprecate, ordependency.NewFeature:work_typeisFeatureorEnhancement, or labels/title contain product terms such asfeature,rollout, orcustomer-request.
Use the first matching category in that order. If no signal matches, choose the closest category by title semantics and document only through the requested JSON fields, not extra prose.
Portfolio Mix Tasks
- Identify scope from the prompt: quarter/date range, teams, product areas, and target
scope_id. - Select in-scope work items by authoritative
team,product_area, and closed date within the quarter. Use closed primary work only. - Exclude duplicates and cancelled/distractor records from the included set. Keep their IDs for any requested exclusion fields.
- Classify included items with the category-resolution rules.
- Fetch the
mix_targetsrow matching the targetscope_id. - Convert target decimals to percentage points. For each category:
count = included item countactual_pct = round(count / total_included * 100, 1); use0.0when the denominator is zerotarget_pct = round(target_decimal * 100, 1)gap_pct = round(actual_pct - target_pct, 1)
- Category row order is usually
NewFeature,TechDebt,Reliability,Security; follow the template if it specifies otherwise. - Sort included IDs by
closed_atascending, then ID ascending, unless the template says another order. - Under-invested categories are categories with negative gaps, ordered from most negative to least negative.
- For rebalance fields, choose the largest negative gap as the primary/largest deficit category. Use the next negative gap as secondary when requested. If no category has a negative gap, use the template's maintain-current-mix option if available.
- For an owner-team recommendation, choose the in-scope team most associated with the deficit category, usually the team with the most included primary work in that category. Break ties by the template or stable alphabetical order.
SLA Aging Tasks
- Identify teams, category set,
as_ofdate, and recent closed window from the prompt. - Classify work items with the category-resolution rules and keep only requested SLA categories, usually
SecurityandReliability. - Primary SLA population:
created_at <= as_of- not duplicate and not cancelled
- in requested teams and categories
- active as of
as_of(closed_atis null or afteras_of) or closed within the recent window ending onas_of
- Duplicate clusters:
- Apply the same scope, category, and time-window logic to duplicate records.
- Group by
duplicate_of. - Sort clusters by
primary_id; sort eachduplicate_idslist ascending.
- Due date:
- Prefer authoritative
due_at. - If
due_atis missing, compute it fromcreated_atplussla_policy.days_to_duefor the item'sseverity.
- Prefer authoritative
- Overdue rule:
- Active item: overdue when
due_at < as_of. - Closed item: overdue when
closed_at > due_at. - A due date equal to
as_ofor a close date equal todue_atis not overdue.
- Active item: overdue when
- Age for bucket counts:
- Use days from
created_attoclosed_atwhen the item closed on or beforeas_of. - Otherwise use days from
created_attoas_of. - Bucket inclusively into
0-3,4-7,8-14,15-30, and31+.
- Use days from
- Breach rate is
overdue_primary_count / included_primary_count, rounded to three decimals; use0.000when the denominator is zero. - Sort ID lists lexicographically unless the template defines a priority order.
- For team overdue counts, list requested teams in template order or alphabetical order and count overdue primary items only.
- For hotspot fields, group overdue primary items by team and owner, using
UNASSIGNEDfor missing owner. Pick the largest count; break ties by team then owner. - For escalation queues, order overdue primary items by severity rank
S1,S2,S3,S4; then by days overdue descending; then by lower numeric priority; then by ID ascending.
Release Readiness Tasks
- Fetch the release, all milestones for that release, work items with matching
release_id, blockers, and dependencies. - Primary release denominator excludes duplicates and cancelled records.
- Milestone completion:
- For each milestone in the release, count primary release work with that
milestone_id. complete_primaryuses the complete status set.completion_pct = round(complete_primary / primary_total * 100, 1); use0.0for empty milestones.- Sort rows by
milestone_idunless the template says otherwise.
- For each milestone in the release, count primary release work with that
- Readiness score is total complete primary work divided by total primary denominator, rounded to three decimals.
- Unresolved blockers have
resolved_atnull and a non-resolved status. High-impact blockers have severityHighorCritical. - Count unresolved high-impact blocker causes by exact
causetext for the release, including blockers attached to complete work. - Gating work item IDs are non-complete primary release items that have unresolved high-impact blockers or are blocked by critical non-complete dependencies. Sort unique IDs ascending.
- Critical dependency chains:
- Build directed paths from
blocked_idtodepends_on_id. - Start from primary release work.
- Follow readiness-impacting relations such as
blocks-release-readiness,security-review-required,validation-required,audit-evidence-required, and implementation dependencies when the prompt treats them as critical. - Stop at the first non-complete primary dependency and output the ordered ID path.
- Do not treat duplicate or cancelled dependency records as primary non-complete blockers unless the prompt asks for data-quality reporting.
- Sort chains lexicographically by the full path.
- Build directed paths from
- Ship decision:
NO_SHIPwhen unresolved high-impact blockers, gating work, or critical non-complete dependency chains remain.SHIP_WITH_WATCHwhen no hard gate remains but lower-severity unresolved blockers, watch items, or incomplete non-gating work remain.SHIPwhen primary release work is complete and no unresolved blockers or critical dependencies remain.
JSON Assembly
- Match the answer template exactly: field names, nesting, enums, required keys, and array/object shapes.
- Preserve specified ordering rules even when JSON object order is not semantically important.
- Round only at the final metric step and use the precision requested by the template.
- Use
nullonly when the template allows it. - Do not include explanatory prose outside the JSON if the prompt asks for JSON only.