# Engineering Portfolio Audits

> Analyze engineering portfolio work-item datasets for portfolio mix, SLA aging, and release-readiness answers. Use when Codex must produce strict JSON from work items, mix targets, SLA policy data, releases, milestones, blockers, and dependencies, especially when records contain duplicates, cancelled items, stale mirror fields, or conflicting category signals.

- Skill: `prism-shadow/engineering-portfolio-audits-3` (Agent Skill)
- Install (CLI): `npx skillmds@latest add prism-shadow/engineering-portfolio-audits-3`
- Raw SKILL.md: https://api.skillmd.com/api/skills/prism-shadow/engineering-portfolio-audits-3/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: prism-shadow (https://skillmd.com/u/prism-shadow)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/prism-shadow/engineering-portfolio-audits-3

---


# Engineering Portfolio Audits

## Core Workflow

1. Read the user prompt and the supplied answer template before calculating. Match the template exactly: required keys, casing, ordering, precision, and no extra prose.
2. Load the relevant runtime access notes and retrieve the authoritative records named by the prompt. Prefer structured queries for cross-checking filters and joins.
3. Build the primary population from explicit scope fields such as team, product area, release, quarter, as-of date, and category. Do not infer scope from ID prefixes.
4. Exclude non-primary records before calculating metrics:
   - Exclude `status == "Duplicate"` and any record with `duplicate_of` set.
   - Exclude `status == "Cancelled"`.
   - Report duplicates, cancellations, or distractors only when the template asks for them.
5. Use authoritative fields for truth. Treat `mirror_status` and `legacy_category` as stale/export fields unless the prompt explicitly asks to flag that they were ignored.

## Portfolio Mix

Use this for closed-work mix reviews.

1. Filter by the prompt's quarter using `closed_at`, with quarter start inclusive and next quarter start exclusive.
2. Require the scoped teams and product areas. Include every matching primary closed item, including non-prefixed IDs.
3. Order included IDs by `closed_at` ascending, then `id` ascending, unless the template says otherwise.
4. Count items, not story points. Compute actual percentages as `count / total * 100`, rounded to one decimal place.
5. Convert target fractions to percentage points. Compute `gap_pct = actual_pct - target_pct`.
6. Under-invested categories are categories with negative gaps, ordered from most negative to least negative.
7. Recommend rebalancing toward the largest negative gap. If a secondary category is required, use the next negative gap. If an owner team is required, infer it from the prompt's team responsibilities and the category/product deficit, not from stale legacy fields.

### Category Resolution

Assign each primary item to exactly one category. Use current `work_type`, labels, and title together; use stale fields only as tie-breaker evidence if the prompt allows it.

- `Security`: security audits, CVE work, compliance/security evidence, auth/encryption work when the item's main intent is security. `work_type` values such as `Security` and security-labeled `Compliance` usually land here.
- `Reliability`: incidents, outages, latency/flaky repair, reliability guardrails, postmortems, and recovery work. `work_type` values such as `Reliability` and `Incident` usually land here.
- `TechDebt`: refactor, migration, cleanup, dependency, deprecation, and chore work when the main intent is maintainability rather than security or reliability.
- `NewFeature`: feature, rollout, enhancement, polish, and user/product capability work when security/reliability terms are incidental or stale.

When signals conflict, prefer the item's main operational intent over a single stale-looking label. For example, a feature rollout with an incidental security label stays `NewFeature`, while a CVE/security patch delivered via dependency work stays `Security`.

## SLA Aging

Use this for security/reliability SLA audits.

1. Build the SLA population from primary Security/Reliability work in the scoped teams.
2. For an as-of audit, include items created on or before the as-of date that are active as of that date, plus primary items closed inside the recent closed window. Treat items closed after the as-of date as active at the as-of date.
3. Exclude records created after the as-of date.
4. Use `due_at` for breach status when present. Use SLA policy only to derive or verify due dates when the prompt or data requires it.
5. Treat open/active work as overdue when `due_at` is before the as-of date. A due date equal to the as-of date is due, not overdue.
6. Treat recently closed work as breached when `closed_at` is after `due_at`.
7. Breach rate is `overdue_or_breached_primary_count / included_primary_count`, rounded to three decimal places.
8. Missing-owner lists include included primary records whose `owner` is null.
9. Duplicate clusters group duplicate IDs under their canonical `duplicate_of` primary ID, with both clusters and duplicate IDs sorted as the template requires.
10. For aging buckets, calculate item age consistently from `created_at` to the as-of date for active items. If the template asks for resolved age, use `closed_at` for recently closed items.
11. Escalation queues should prioritize active overdue work by `priority` ascending, then severity (`S1` before `S2` before `S3` before `S4`), then oldest `due_at`, then `id`. Include closed breaches in the queue only if the template defines the queue as all overdue primary IDs.

## Release Readiness

Use this for release ship/no-ship assessments.

1. Primary release work is work with the target `release_id`, excluding duplicates and cancellations.
2. Complete statuses are `Closed`, `Done`, `Verified`, and `Deployed`. Non-complete statuses include `Backlog`, `In Progress`, `Review`, and `Reopened`.
3. Milestone completion uses all milestones for the release, sorted by milestone ID. For each milestone, count complete primary work and total primary work, then round completion percentage to one decimal place.
4. Gating work item IDs are non-complete primary release items, sorted with no duplicates.
5. Unresolved high-impact blocker counts include blockers with no resolution and high-impact severities such as `High` or `Critical`. Count by exact `cause` text.
6. Dependency chains are ordered paths from release work to a non-complete dependency when dependency records indicate release readiness, validation, security review, audit evidence, or an explicit blocking relationship. Sort chains lexicographically by the full path.
7. Readiness score is complete primary release work divided by primary release work, rounded to three decimal places.
8. Use `NO_SHIP` when critical/high-impact unresolved blockers or non-complete readiness gates remain. Use `SHIP_WITH_WATCH` for low-risk unresolved watch items, and `SHIP` only when primary work is complete and no readiness blockers remain.

## Output Discipline

- Return exactly the JSON object requested by the template.
- Preserve enum casing such as `NewFeature`, `TechDebt`, `Reliability`, and `Security`.
- Use lexicographic ID ordering unless the template specifies date ordering.
- Round only at the output boundary.
- Do not include source notes, calculations, or prose outside the JSON.