vamseeachanta repo-portfolio-steering Skill
One-page portfolio steering report: harness/engineering balance, GTM-readiness ranking, per-provider agentic activity, and the next 3 highest-leverage actions to fund.
Quick Start
# Full steering report (run from workspace-hub root)
uv run --no-project python scripts/skills/repo-portfolio-steering/compute-balance.py
# Custom threshold
uv run --no-project python scripts/skills/repo-portfolio-steering/compute-balance.py --threshold 0.25
# With portfolio signals (Layer 2)
uv run --no-project python scripts/skills/repo-portfolio-steering/compute-balance.py \
--signals .Codex/state/portfolio-signals.yaml
5 Output Sections
Section 1 — Balance Snapshot (L1)
Reads ## By Category summary table from INDEX.md.
| Category | Count | % | Status |
|---|---|---|---|
| harness | N | N% | ✓ / ⚠ |
| engineering | N | N% | — |
Threshold: harness_threshold in frontmatter (default 30%).
- ≤ threshold →
HEALTHY threshold →
OVER-INVESTED
Section 2 — Harness Saturation Signal
Layer 1 — Queue balance (from INDEX.md):
- Default threshold: 30% configurable via
HARNESS_THRESHOLD - Output:
HEALTHYorOVER-INVESTED+ recommended max harness items before returning to engineering
Layer 2 — Agentic activity by provider (from .Codex/state/portfolio-signals.yaml):
Provider | Harness (30d) | Engineering (30d) | Harness%
Codex | 4 | 3 | 57% ⚠ OVER
codex | 1 | 5 | 17% ✓
gemini | 0 | 2 | 0% ✓
Source: portfolio-signals.yaml provider_activity section.
If file is absent, Layer 2 is skipped (graceful degradation).
Layer 3 — Capability research (deferred to WRK-1020):
capability_signals key will be added by the nightly cron without breaking L1+L2.
Section 3 — GTM-Ready Technical Capabilities
Ranks active engineering WRK items by demo-readiness:
- Rank criteria:
brochure_status(ready > updated > draft > n/a) - Secondary:
percent_completedescending - Tertiary: WRK ID ascending (older = more considered)
| WRK | Domain | Brochure | % Done | Demo Ready? |
|---|
Section 4 — Next 3 Actions to Fund
Top 3 HIGH-priority engineering items mapped to GTM opportunities:
| WRK | Domain | Client Persona | Project Type | Action |
|---|
Domain → Client Persona → Project Type mapping:
| Engineering Domain | Client Persona | Project Type |
|---|---|---|
| subsea pipeline / DNV RP F105 | Offshore operator / pipeline integrity engineer | VIV/freespan assessment |
| cathodic protection | Corrosion engineer / asset manager | CP system design report |
| marine / hydrodynamics | Naval architect / offshore designer | Motions & loads study |
| drilling / ROP models | Drilling engineer / well planner | Drilling performance analysis |
| production forecasting / Arps | Reservoir engineer / E&P consultant | Decline curve + reserves |
| net lease / CRE | Real estate investor / asset manager | NNN lease underwriting |
| structural / FEA | Structural engineer / EPC contractor | Plate/beam design check |
Section 5 — Recommended Harness Budget
Spend-rate formula based on current harness_pct:
| harness_pct range | Budget rule |
|---|---|
| ≤ 15% | 1 harness per 3 engineering (ramp up harness) |
| 15%–30% | 1 harness per 5 engineering (maintain) |
| > 30% | 0 harness — pure engineering until below threshold |
Runtime Inputs
| Input | Path | Purpose |
|---|---|---|
| Category View | .Codex/work-queue/INDEX.md ## By Category |
Balance snapshot |
| WRK frontmatter | pending/*.md + working/*.md |
brochure_status, category, priority |
| Portfolio signals | .Codex/state/portfolio-signals.yaml |
L2 provider activity + L3 capability |
Session-Start Integration
This skill registers a weekly steering mode for /session-start:
- Trigger: user invokes
/repo-portfolio-steeringOR session-start detects--mode weekly - Output replaces the "top items per category" summary with the full steering report
- No changes to session-start SKILL.md body — steering invoked as a delegate
Acceptance Criteria
- AC-1: SKILL.md at
.Codex/skills/workspace-hub/repo-portfolio-steering/SKILL.md - AC-2: Balance snapshot reads INDEX.md By Category
- AC-3: Harness threshold default 30% + configurable
- AC-4: GTM-readiness ranking by brochure_status + percent_complete
- AC-5: Next 3 to fund maps domains to client personas
- AC-6: Recommended harness budget outputs spend-rate
- AC-7: Harness saturation signal includes per-provider activity (Layer 2)
- AC-8: capability_signals key present does not crash (L3 compat)
- AC-9: Missing portfolio-signals.yaml graceful (no crash)
- AC-10: Session-start integration point documented
- AC-11: Description triggers on portfolio/steering/harness phrases