Portfolio Status Skill

Procedural knowledge for generating comprehensive portfolio health reports across all initiatives.

When to Use

• Running /status-all command

• Answering "where are we across everything?"

• Weekly/daily status reviews

• Identifying portfolio-wide blockers and gaps

• Prioritizing what to work on next

Data Sources

Scan initiative folders organized by status:

pm-workspace-docs/initiatives/ ├── active// # Active initiatives (mapped 1:1 to Notion Projects DB) - PRIMARY scan target │ ├── _meta.json # Phase, status, priority, notion_project_id │ ├── research.md # User research │ ├── prd.md # Product requirements │ ├── design-brief.md # Design specifications │ ├── engineering-spec.md # Technical spec │ ├── prototype-notes.md # Prototype documentation │ ├── gtm-brief.md # Go-to-market plan │ └── jury-evaluations/ # Validation results ├── done// # Completed initiatives (Notion Phase = Done) - include in portfolio counts ├── archived/*/ # Local-only, not in Notion - EXCLUDE from portfolio status └── _template/ # Template - EXCLUDE

IMPORTANT: Portfolio status should primarily scan active/ and done/ . Exclude archived/ and _template/ .

Also load:

• pm-workspace-docs/roadmap/roadmap.json

• Priority and phase data

• pm-workspace-docs/signals/_index.json

• Linked signals

• pm-workspace-docs/status/history.json

• Previous snapshots (if exists)

• pm-workspace-docs/status/dev-status-*.json

• Latest dev status (if exists)

• pm-workspace-docs/initiatives/active/*/metrics-contract.json

• Measurement readiness coverage

MCP Tools Available (Optional Enhancement)

Server: composio-config (Composio)

Use MCP tools to enrich portfolio status with live data:

Source Tools Enhancement

Linear LINEAR_LIST_LINEAR_PROJECTS , LINEAR_SEARCH_ISSUES

Pull live issue counts, cycle progress

PostHog POSTHOG_RETRIEVE_PROJECT_INSIGHTS , POSTHOG_RETRIEVE_PROJECT_INSIGHT_DETAILS

Pull success metric values for initiatives with dashboards

Notion NOTION_QUERY_DATABASE

Cross-reference with Notion Projects DB

Slack SLACK_SEARCH_MESSAGES

Check for recent activity mentions

When to use:

• /status-all --live → Query Linear/PostHog for real-time data

• Health scoring → Use PostHog metrics to validate initiative health

• Blockers → Check Linear for blocked issues

Analysis Framework

Step 1: Discover All Initiatives

List all directories in pm-workspace-docs/initiatives/active/ and pm-workspace-docs/initiatives/done/ excluding:

• _template/

• Template folder

• archived/

• Local-only initiatives not in Notion Projects DB

• Any folder starting with . or _

Note: Active initiatives are now 1:1 mapped with Notion Projects. Each _meta.json contains a notion_project_id field.

Step 2: Collect Initiative Data

For each initiative, extract from _meta.json :

{ "id": "initiative-name", "phase": "discovery | define | build | validate | launch", "status": "on_track | at_risk | blocked | paused", "priority": "P0 | P1 | P2 | P3", "owner": "name", "personas": [], "pillar": "pillar-name", "updated_at": "ISO8601", "created_at": "ISO8601", "blockers": [], "jury_results": { "pass_rate": 0.0 } }

If _meta.json is missing, mark as incomplete_metadata .

Step 3: Check Artifact Completeness

For each initiative, check file existence:

Artifact File Status

Research research.md

✅ exists / ❌ missing

PRD prd.md

✅ exists / ❌ missing

Design Brief design-brief.md

✅ exists / ❌ missing

Engineering Spec engineering-spec.md

✅ exists / ❌ missing

Prototype prototype-notes.md

✅ exists / ❌ missing

GTM Brief gtm-brief.md

✅ exists / ❌ missing

Jury Evaluation jury-evaluations/*.md

✅ exists / ❌ missing

METRICS METRICS.md

✅ exists / ❌ missing

Metrics Contract metrics-contract.json

✅ exists / ❌ missing

Decisions decisions.md

✅ exists / ❌ missing

Artifact Completeness % = (artifacts present / total expected for phase) * 100

Expected artifacts by phase:

• Discovery: Research

• Define: Research, PRD, Design Brief, Decisions

• Build: Research, PRD, Design Brief, Engineering Spec, Prototype Notes, METRICS, Metrics Contract, Decisions

• Validate: All above + Jury Evaluation

• Launch: All artifacts including GTM Brief

Step 4: Calculate Staleness

Days in Phase Status

0-7 🟢 Fresh

8-14 🟡 Monitor

15-21 🟠 Stale

22+ 🔴 Very Stale

Calculate days_in_phase from _meta.json.updated_at or phase_history .

Step 5: Assess Graduation Readiness

For each initiative, check if ready to advance:

Discovery → Define

• research.md exists with content

• User problems documented

• Primary JTBD articulated

• Personas identified in _meta.json

• Owner assigned in _meta.json

Define → Build

• prd.md exists

• design-brief.md exists

• Outcome chain defined

• E2E experience addressed (all 5 steps)

• Feedback method defined (_meta.json.feedback_method set)

• decisions.md exists

Build → Validate

• prototype-notes.md exists

• States documented (Loading, Error, Empty, Success)

• Chromatic URL or prototype location

• Discovery and activation flows prototyped

• METRICS.md exists with baselines or plan

• metrics-contract.json exists with validation.status

Validate → Launch

• Jury pass rate ≥70%

• All 5 experience steps validated

• Stakeholder approval

• No P0 blockers

• gtm-brief.md exists with customer story and launch materials

• Success metric baselines established

• Measurement readiness status tracked (metrics-contract.json )

• Feedback instrument planned or live

Ready to Advance = All criteria met for current phase transition

Step 6: Calculate Portfolio Health Score

Metric Weight Score Calculation

No blocked initiatives 25 25 if 0, 15 if 1, 0 if 2+

Artifact completeness 25 (avg completeness %) * 0.25

No stale initiatives 20 20 if 0, 10 if 1-2, 0 if 3+

Phase distribution 15 See balance check below

Jury pass rates 15 (avg pass rate where available) * 0.15

Phase Distribution Balance:

• Ideal: 10-20% discovery, 20-30% define, 30-40% build, 10-20% validate

• Score 15 if within ranges, 8 if slightly off, 0 if severely imbalanced

Total Health Score = Sum of all metric scores (0-100)

Step 7: Generate Action Queue

Prioritize actions using this algorithm:

Score = (Priority_Weight * 10) + (Blocking_Impact * 5) + (Quick_Win * 3) + (Graduation_Ready * 2)

Priority_Weight:

• P0 = 4
• P1 = 3
• P2 = 2
• P3 = 1

Blocking_Impact:

• Blocks other initiatives = 2
• Blocks same initiative = 1
• No blocking = 0

Quick_Win:

• Can complete in <1 hour = 2
• Can complete in <1 day = 1
• Longer = 0

Graduation_Ready:

• Ready to advance with this action = 2
• Partially ready = 1
• Not ready = 0

Sort actions by score descending, limit to top 10.

Step 8: Include Dev Activity Data

If dev_activity exists in _meta.json , include in analysis:

{ "dev_activity": { "last_synced": "2026-01-23T18:00:00Z", "linear_issues_total": 57, "linear_issues_completed": 23, "linear_issues_in_progress": 10, "github_prs_merged_30d": 15 } }

Dev Progress Calculation:

• If linear_issues_total

0: completed / total * 100

• Show as percentage in artifact matrix

Activity Flags:

• High Activity: >5 issues in progress OR >3 PRs in last 7 days

• Stale Code: >14 days since last PR with >0 issues in progress

• Docs Drift: High activity but docs >14 days stale

Add to Health Score (optional boost):

• Active development with current docs: +5 points

• High activity with stale docs: -5 points (alert)

Step 9: Compare to History (Trends)

If pm-workspace-docs/status/history.json exists, compare:

• Health score change (↑ improved, ↓ declined, → stable)

• Phase advances since last check

• New blockers since last check

• Initiatives added/removed

Output Formats

Markdown Report (Default)

Portfolio Status Report

Generated: YYYY-MM-DD HH:MM Health Score: XX/100 [↑/↓/→]

Executive Summary

Attention Required

Artifact Gap Matrix

Legend: ✅ Complete | ⚠️ Incomplete | ❌ Missing | - Not required yet | MC = Metrics Contract | Dev = Linear progress %

Measurement Readiness Coverage

Dev Activity Alerts

Ready to Advance

Prioritized Action Queue

Phase Distribution

Trends (vs. [previous date])

• Health: XX → XX ([change])
• Phase Advances: +X
• New Blockers: X
• Stale → Active: X

All Initiatives

JSON Output

{ "generated_at": "ISO8601", "health_score": 78, "health_trend": "up", "summary": { "total": 19, "by_priority": { "P0": 7, "P1": 5, "P2": 4, "P3": 3 }, "by_phase": { "discovery": 2, "define": 5, ... }, "by_status": { "on_track": 15, "at_risk": 3, ... }, "ready_to_advance": 3, "need_attention": 2 }, "attention_required": [ { "id": "initiative-name", "issue": "Stale (21 days)", "action": "/status initiative-name" } ], "artifact_matrix": [ { "id": "initiative-name", "phase": "build", "artifacts": { "research": "complete", "prd": "complete", "design_brief": "missing", "engineering_spec": "incomplete", "prototype": "complete", "jury": "not_required", "metrics_contract": "incomplete" }, "completeness": 0.67, "measurement_readiness": "partial", "dev_activity": { "linear_progress": 0.40, "issues_in_progress": 8, "prs_merged_30d": 15, "last_synced": "2026-01-23T18:00:00Z" }, "alerts": ["docs_drift"] } ], "ready_to_advance": [...], "action_queue": [...], "initiatives": [...], "previous_snapshot": { "date": "ISO8601", "health_score": 75 } }

Command Options

Option Description

(none) Full portfolio report

--priority P0

Filter to P0 initiatives only

--phase build

Filter to build phase only

--stale

Only show stale/at-risk initiatives

--json

Output JSON format only

--no-save

Don't save to status folder

Saving Results

After generating report:

• Save markdown to pm-workspace-docs/status/status-all-YYYY-MM-DD.md

• Save JSON to pm-workspace-docs/status/status-all-YYYY-MM-DD.json

• Update pm-workspace-docs/status/history.json with snapshot

History JSON format:

{ "snapshots": [ { "date": "2026-01-23", "health_score": 78, "total_initiatives": 19, "by_phase": {...}, "by_status": {...} } ] }

Edge Cases

No Initiatives Found

⚠️ No initiatives found in pm-workspace-docs/initiatives/active/

Create your first initiative with: /new-initiative [name]

All Initiatives Missing Metadata

⚠️ Found X initiatives but none have _meta.json files.

Run /maintain fix to generate metadata for all initiatives.

First Run (No History)

ℹ️ First portfolio status run - no historical data for comparison.

Future runs will show trends.

Integration with Other Commands

After generating status, suggest relevant follow-ups:

• Stale initiative → /status [name] for details

• Missing artifacts → /pm [name] or /proto [name]

• Failed jury → /iterate [name]

• Ready for launch → /share

• Phase imbalance → /roadmap for prioritization

• Missing dev data → /sync-dev to refresh Linear/GitHub data

• Docs drift alert → Update stale docs for active initiatives

• No Linear mapping → /sync-linear --map to suggest mappings

Dev Pipeline Integration

Running with Fresh Data

For most accurate view, run sync first:

/sync-dev # Refresh Linear + GitHub data /status-all # Generate status with fresh dev activity

Alert Types

Alert Condition Recommended Action

docs_drift

Dev activity high, docs >14 days stale Update research/PRD

no_linear

Missing linear_project_id

Run /sync-linear --map

stale_code

Issues in progress, no PRs in 14 days Check blocked work

high_activity

5 issues active May need phase advancement

Dev Activity in Health Score

Base health score calculation remains unchanged. Dev activity provides:

• Context: Understand if an initiative is active even if docs are stale

• Alerts: Surface initiatives where code and docs are out of sync

• Velocity: Track shipping rate per initiative