/review-proposals

name: review-proposals
description: "Triages pending improvement-proposal MCP items — presents each with its scope and evidence, collects an accept/reject/defer decision per proposal, and carries out the disposition: project-scoped acceptances get their exact YAML applied to .taskorchestrator/config.yaml and pushed per-root; global acceptances get a tracked GitHub issue (or dwell in review for the maintainer); rejections are recorded and cancelled; deferrals are recorded and left in queue. Use when a user says: review proposals, triage proposals, pending proposals, what proposals are open, adopt proposals, process improvement proposals, accept or reject proposals."
argument-hint: "[optional: proposal UUID | --scope global|project]"

Review Proposals

Triages `improvement-proposal` MCP items created by `/session-retrospective` when a cross-session trend graduates. Presents pending proposals, collects a per-proposal decision, and carries out the disposition — including applying project-scoped config changes and filing/linking GitHub issues for global changes.

Shared GitHub conventions (issue template, scrub rule, `gh` guard, dedup procedure) are **not** duplicated here — see `<skill-base-dir>/../session-retrospective/references/github-feedback.md` for the full C2/C4/C5 contract and dedup steps referenced throughout Step 5.

---

Step 0 — Parse Arguments and Read Config

Parse `$ARGUMENTS`:

• **A UUID** → single-proposal mode: skip Step 1 discovery entirely: go straight to Step 2 for

that one item.

• **`--scope global` or `--scope project`** → filter Step 1 discovery to only that scope's query.

Absent → run both discovery queries.

• Neither → full discovery, both scopes.

Read the config file directly (file read, not MCP) — the path on the SessionStart context's `Config:` line when there is one, otherwise the workspace `.taskorchestrator/config.yaml`. In personal scope that path is the user-level file; below, "the config file" means whichever file you read here. Read it for:

• `project.rootId` / `project.name` — enables the project-scoped discovery query and per-root push

in Step 5. In personal scope the root is the anchor-only personal root: skip the project-scoped discovery query (proposals live in the global container) but a project-scoped acceptance still edits and pushes the user-level file with rootId = the personal root. If absent, project-scoped discovery and project-scoped acceptance are unavailable — proceed with global-only discovery.

• `retrospective.github_feedback.enabled` — default `false` if the block or key is absent.
• `retrospective.github_feedback.repo` — default `jpicklyk/task-orchestrator` if absent.

---

Step 1 — Discovery

**Skip this step entirely in single-proposal mode (UUID argument supplied).**

Run both queries in parallel (unless `--scope` narrows to one):

**Global:**

query_items(operation="search", query="Improvement Proposals", limit=5)

Find the "Improvement Proposals" container from the result, then:

query_items(operation="overview", anchorId="<container-uuid>", includeChildren=true)

**Project-scoped** (only if `project.rootId` is known):

query_items(operation="search", tags="improvement-proposal", ancestorId="<rootId>", limit=50)

Partition results

For each candidate item, classify by role and notes:

• **Pending** — role `queue`, no `adoption-decision` note yet. The main triage set.
• **Deferred** — role `queue`, has an `adoption-decision` note whose body starts with "deferred".

List in a **separate section**; do not re-offer for a decision unless the user explicitly asks to revisit deferred proposals, or the stated revisit condition in the note plausibly holds now.

• **Stalled** — role `work` (item was accepted and advanced to `work` via `start` but never reached

`review`/terminal — an interrupted or stuck adoption). Flag as **stalled adoption**; offer to resume (fill remaining notes and `complete`) or cancel.

• **Terminal** — skip; already resolved (accepted-and-verified, rejected, or fully handed off).

**If nothing is pending** (no queue-role items without an adoption-decision, and no stalled items), report:

No pending improvement proposals.

and stop — do not proceed to later steps.

---

Step 2 — Load Proposal Detail

For each candidate (pending + stalled; cap at 15 — if more, take the 15 oldest by creation and note the overflow count), fetch notes:

query_notes(operation="list", itemId="<uuid>", includeBody=true)

From the returned notes, extract:

• **Proposal body** — the `proposal` note (or the item's `summary` if the note is absent).
• **Scope clause** — read the scope classification the note states (global vs project-specific).

If it cannot be parsed unambiguously, **treat as global** — this is conservative: never auto-edit a project's `config.yaml` on an ambiguous scope reading.

• **Existing `github-issue:` line** — the last line of the proposal note body, if present, in the

form `github-issue: <url>`. Carry this forward so Step 5's global-accept path can reuse it instead of filing a duplicate.

---

Step 3 — Present Triage Table

Render one compact table covering all pending + stalled candidates (deferred proposals get their own short list underneath, not full rows):

| # | ID | Proposal | Scope | Evidence | Age | Issue |
|---|-----|----------|-------|----------|-----|-------|
| 1 | `a1b2c3d4` | Add `session-tracking` maxLength guard | project | 3 sessions, sparse-note trend | 4d | — |
| 2 | `e5f6a7b8` | Nudge cooldown too short for solo dev | global | 2 sessions, friction theme | 1d | #142 |

• **Evidence** — a one-line summary of the trend/session count that graduated this proposal (from

the proposal body or summary).

• **Age** — days since creation.
• **Issue** — existing `github-issue:` link if present, else `—`.

Below the table, list deferred proposals as a short reminder line each: `` `<short-id>` — deferred: <condition>