Brief: weekly portfolio review MVP

TL;DR: Build and test an MVP of the weekly portfolio review for Weekly Portfolio Review (2620). An AI runs the review in five steps (sweep, gaps, shortlist, drill down, harvest), stopping where Rufus gives feedback. It produces an agent-readable file and a human-readable page rendered from it. Done when a fresh Sonnet or Opus agent can run it end to end from the skill alone on real data. Source: Rufus's instructions in chat, 26 Oct 2026, and his dictation.

Mini SCQ

Situation: project records now live in each project's repository. A sweep caches them in planning (portfolio/projects-cache.json, portfolio/index.js) and renders Projects by initiative. Weekly team plans go in weeks/. The planning skill has a task-level sweep and a week mode.
Complication: nothing yet takes us from "all projects" to "this week's few, their key tasks, and what we write back". Gaps (missing records) were found by hand on 22 Oct. The table has no priority, mixes iced and active work, and is built for reading, not for an AI to work from. Each weekly plan starts from a blank page.
Question: what is the smallest repeatable review, run by an AI, that gets from every project to an agreed weekly plan, with Rufus steering at the right points?

The five steps

Sweep. Refresh the project cache. The agent works from the JSON (projects-cache.json or index.js), not the Markdown table; the table is for people.
Gaps. Find what is missing: active repositories with no project record, open Beads epics with no project, records with no owner, phase or done-when, and stale records. Suggest a fix for each. Automate what was done by hand in the 22 Oct candidates note.
Shortlist. Show the human view: every project with initiative as its own column, its last logged priority, phase, status and owner. Group so the eye goes to live choices: the ice box (paused, someday, backlog and anything already iced in an earlier plan) is collapsed to one line each or a separate section. Add the AI's suggested shortlist with a one-line reason each, and questions. Gate: Rufus reprioritises by talking; the agent updates the file and re-renders; repeat until agreed.
Drill down. For each shortlisted project: is planning done (record, done-when, issue tree)? Is the implementation route clear (an epic with ready tasks)? What are the 1–3 key tasks this week, by existing Beads ID? Flag "needs planning", "needs a next action" or "ready to build". Gate: Rufus confirms or adjusts.
Harvest. Separate what is written back for good from what is only for this week:
- Permanent, in the project's own record: phase, status, owner, priority on initiatives, new records for gaps, dated status notes.
- This week only, in the week plan: the shortlist, its order, key tasks, the week's goal (what we expect to ship).
- Beads to create or update (owner, priority, due only when fixed).
- A short per-person summary of their main areas this week. Writes outside planning are proposed and applied only on Rufus's confirmation.

Outputs

One agent-readable file per review (structured, e.g. JSON or YAML) that holds the state across steps: projects, gaps, shortlist, drill-down, harvest. Re-running a step updates it.
A human-readable page rendered from it by a script, so feedback shows straight away. A live view is a later step.
The agreed week plan in weeks/YYYY-MM-DD.md (the existing format), written at harvest.

Constraints

Priorities: project priority is set week to week in the week plan (data model); "last logged priority" means the latest week plan or roadmap value, shown as history, not as truth.
Read records from their own repositories via the sweep; the record wins over any cache.
Keep it one coordinating mode in the planning skill unless a step clearly needs its own skill. Scripts do the mechanical work (sweep, gap detection, render); the AI does judgment (suggestions, reasons, questions).
Don't write weeks/2026-10-26.md in this build: another session may be planning this week. The MVP's own trial output goes in docs/plans/.

How we build it

Design: a Fable subagent reviews this brief and the existing scripts and proposes the file format, script changes and skill steps.
Build: Sonnet or Opus implements the scripts and the skill mode.
Test: fresh Sonnet and Opus subagents run the review from the skill alone on real data, playing Rufus's feedback at the gates from a short script. Fix what fails, then rerun.

Done when

A fresh Sonnet agent, given only "use the planning skill, run the weekly review", produces the human page with a complete table, a gap list with suggested fixes, a suggested shortlist with reasons and questions, drill-down flags with key tasks, and a harvest list split into permanent and this-week.
A simulated reprioritisation changes the file and the re-rendered page.
The trial output for the week of 26 Oct is ready for Rufus to react to.