oat-pjm-review-backlog

name	oat-pjm-review-backlog
version	1.5.0
description	Use when prioritizing the file-backed repo backlog or evaluating roadmap alignment. Produces value-effort ratings, dependency mapping, execution recommendations, and an optional external-plan handoff.
argument-hint	[backlog-root] [--roadmap=<path>] [--output=<path>]
disable-model-invocation	true
allowed-tools	Read, Write, Glob, Grep, Bash(git:*), AskUserQuestion, Task
user-invocable	true
metadata	{"internal":true}

Review Backlog

Analyze the file-backed backlog under .oat/repo/pjm/backlog/ to produce a structured review with value-effort ratings, dependency graph, parallel work lanes, and a recommended execution sequence. Optionally cross-reference a roadmap to identify alignment gaps.

Mode Assertion

OAT MODE: Backlog Review

Purpose: Review active backlog item files, evaluate roadmap alignment, and recommend a practical execution order.

Reference Format Convention

Whenever a backlog item is referenced — in the written review document, in chat output, or in the inline summary at the end — it must include both the ID and a human-readable title. Bare IDs like BL-260529-control-plane-state-read are not acceptable in user-facing output, because readers do not have a board lookup in front of them.

Use one of these formats:

• Inline / prose: `BL-260529-control-plane-state-read` (control-plane state-read migration)
• Tables / lists: **BL-260529-control-plane-state-read** — Control-plane state-read migration
• Compact lists where space is tight (e.g., dependency graphs): an ID-only token is acceptable only if a legend in the same section maps every ID to its title.

This convention applies equally to:

• The "Top recommended next actions" summary
• Risks, gaps, and quick-wins callouts
• Any chat-level commentary about specific items
• All tables and item references in the written review document

If a title is missing from frontmatter, derive a short noun phrase from the item filename or ## Description heading rather than falling back to a bare ID.

Progress Indicators (User-Facing)

When executing this skill, provide lightweight progress feedback so the user can tell what’s happening after they confirm.

• Print a phase banner once at start using horizontal separators, e.g.:

  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ OAT ▸ REVIEW BACKLOG ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

• Before multi-step work, print short step indicators, e.g.:

  • [1/8] Resolving backlog inputs…
  • [2/8] Cataloging backlog items…
  • [3/8] Reading codebase context…
  • [4/8] Writing review document…
  • [5/8] Summarizing recommendations…
  • [6/8] (Optional) Priority-alignment walkthrough… — only print after the operator accepts the offer in Step 9
  • [7/8] (Optional) Refreshing project kickoff handoffs… — only print after the operator agrees a kickoff stack in Step 10
  • [8/8] (Optional) Handing selected items to repo improve… — only print after the operator accepts the offer in Step 11

Arguments

Parse from $ARGUMENTS:

• backlog-root: (optional) Path to the backlog root directory. Defaults to .oat/repo/pjm/backlog/.
• --roadmap=<path>: (optional) Path to a roadmap document for alignment analysis.
• --output=<path>: (optional) Where to write the living review. Defaults to .oat/repo/pjm/backlog/reviews/backlog-and-roadmap-review.md.
• --archive-dated: (optional) Also write a dated snapshot alongside the living review at .oat/repo/pjm/backlog/reviews/backlog-and-roadmap-review-YYYY-MM-DD.md. Default: off.

Process

Step 1: Locate Inputs

Backlog root:

1. If backlog-root is provided, use it directly.
2. Otherwise, default to .oat/repo/pjm/backlog/.
3. Confirm these inputs exist:
   • backlog/index.md
   • backlog/items/*.md
   • backlog/completed.md
4. If multiple candidate roots are found, ask the user to pick.

Roadmap document (optional):

1. If --roadmap is provided, use it directly.
2. Otherwise, look for .oat/repo/pjm/roadmap.md.
3. Ask the user whether to include roadmap alignment if a roadmap is available.

Output path:

1. If --output is provided, use it directly.
2. Otherwise, default to .oat/repo/pjm/backlog/reviews/backlog-and-roadmap-review.md (the living, single-file review co-located with the backlog).
3. If the backlog/reviews/ directory does not exist yet, create it before writing. Do not fall back to .oat/repo/reviews/ — backlog review artifacts now live under the file-backed backlog, not the repo-wide reviews directory.

Dated snapshot (optional):

If --archive-dated is passed, also write a copy to .oat/repo/pjm/backlog/reviews/backlog-and-roadmap-review-YYYY-MM-DD.md in the same directory as the living review. Do not write dated snapshots to .oat/repo/reviews/.

Step 2: Read and Catalog Backlog Items

Read all active backlog item files from backlog/items/*.md.

For each item, capture:

• ID: Use the item frontmatter id when present; if missing, assign a stable sequential review ID (B01, B02, ...)
• Title: Frontmatter title
• Priority: Frontmatter priority
• Scope: Frontmatter scope
• Status: Frontmatter status
• Labels / assignee / linked issues: Any relevant frontmatter context
• Notes/context: Key details from ## Description and ## Acceptance Criteria

Also read:

• backlog/index.md for curated overview notes
• backlog/completed.md for recent completions
• backlog/archived/*.md only when historical context is needed for an active item

Step 3: Understand Codebase Context

Before rating items, build enough context to assess effort accurately:

1. Read relevant codebase areas referenced by backlog item files.
2. Check existing CLI, skills, templates, and reference docs to understand reusable patterns.
3. Note dependencies implied by current implementation state.

Use the Explore agent for broad codebase exploration if needed. Use direct Read/Glob/Grep for targeted lookups.

Step 4: Rate Each Item

For each active backlog item, assess:

Value (High / Medium / Low):

• High: Unblocks other items, significant workflow impact, or roadmap-critical
• Medium: Improves consistency or quality but does not block other work
• Low: Nice-to-have, speculative, or narrow audience

Effort (High / Medium / Low):

• High: > 3 days, broad or cross-cutting work
• Medium: 1-3 days, moderate complexity, well-scoped
• Low: < 1 day, isolated and straightforward

Quadrant (derived):

• Quick Win
• Strategic
• Fill-in
• Avoid / Defer

Provide a brief rationale for each rating.

Step 5: Map Dependencies and Parallel Lanes

For each item, identify:

• Hard dependencies
• Soft dependencies
• What it blocks

Then group items into independent parallel lanes and organize them into recommended execution waves.

Step 6: Roadmap Alignment

If a roadmap was provided:

1. Map backlog item files to roadmap horizons or phases.
2. Identify roadmap work with no backlog coverage.
3. Identify backlog items not represented on the roadmap.
4. Check whether roadmap status wording is consistent with active backlog reality.

Step 7: Write the Review Document

Use the template at .agents/skills/oat-pjm-review-backlog/references/backlog-review-template.md.

Write the living review to the resolved output path (default .oat/repo/pjm/backlog/reviews/backlog-and-roadmap-review.md). If --archive-dated was passed, also write a dated snapshot alongside it (backlog-and-roadmap-review-YYYY-MM-DD.md in the same directory). Never split living and dated outputs across different directories — they must live together under backlog/reviews/.

Ensure:

• Every active backlog item file appears in the item catalog
• Dependency graph and parallel lanes are explicit
• Execution waves are actionable
• Roadmap alignment is included when applicable

Step 8: Summarize for the User

After writing the review, provide:

• Total active items reviewed
• Distribution across quadrants
• Top 3 recommended next actions
• Key risks or gaps discovered

When listing specific items in this summary, follow the Reference Format Convention above — every backlog item must appear as `BL-YYMMDD-slug` (human-readable title) (or the bold-with-em-dash variant in tables). Do not emit bare IDs.

Step 9: Offer Priority Alignment Walkthrough (Optional, Collaborative)

The full review answers "what's in the backlog and how is each item rated." Operators still have to mentally extract "what should I actually do next, and in what order, with what parallelism." priority-alignment.md is the one-page execution companion that makes that extraction explicit.

This step is optional and collaborative — it requires operator context (recent ships, capacity, calendar, ongoing initiatives) that the skill alone does not have. Do not produce or refresh priority-alignment.md without operator participation.

Decision: should we run the walkthrough?

After the summary, ask the operator:

Want to walk through the review together and produce a one-page execution view at backlog/reviews/priority-alignment.md? It captures phased order, parallelism, and a recommended kickoff stack — a faster reference than the full review.

If .oat/repo/pjm/backlog/reviews/priority-alignment.md already exists, frame it as an update to the existing document rather than a fresh create. Read the existing file first so the walkthrough builds on it.

If the operator declines, skip Steps 9–10 and continue to the Step 11 external-plan offer. Do not silently write or modify priority-alignment.md.

If the operator accepts, run the walkthrough:

1. Propose a phase breakdown based on the review's quadrants and dependency graph:
   • "Finishing / in flight" — items already started or in code review
   • One or more execution phases that group items by initiative, parallel lane, or sequencing constraint
   • Surface the natural parallelism boundaries from Step 5 as parallel tracks within a phase
2. Solicit operator context that the review alone cannot capture:
   • What just shipped or changed since the last alignment? (Goes in the Status line and Changelog.)
   • What's the operator's capacity / appetite for parallel work this cycle?
   • Are there calendar constraints (freezes, releases, time off) that affect ordering?
   • Does the operator want an optional axis like "planning investment" or "design effort" as a column? (Some repos find this useful; many don't. Default: omit unless operator opts in.)
3. Iterate on phase names, ordering, and the kickoff stack until the operator is satisfied. Phase names should reflect the repo's actual initiatives, not generic placeholders.
4. Write or update .oat/repo/pjm/backlog/reviews/priority-alignment.md using the template at .agents/skills/oat-pjm-review-backlog/references/priority-alignment-template.md. Add a new Changelog entry summarizing what shifted in this pass.
5. Confirm the result with the operator: file path, top-of-doc Status line, and the kickoff stack.

When referencing backlog items inside the priority-alignment doc, the Reference Format Convention still applies — link to the item file and pair the ID with a human-readable title.

Step 10: Refresh Project Kickoff Handoffs (Optional)

When a priority-alignment pass concludes (Step 9), generate or refresh one kickoff handoff per item in the agreed kickoff stack. A handoff is a one-shot kickoff prompt — consumable context for turning a backlog item into a project, not durable documentation. The item file and reference/ remain the source of truth. Handoffs live under .oat/repo/pjm/handoffs/; see that directory's README.md for the convention (generated by oat pjm init).

This step mirrors the Project Kickoff Handoffs section of the pjm instruction template (pjm/AGENTS.md) — follow that section's semantics; do not invent divergent wording. It is collaborative and human-gated: kickoff-stack membership, lane count, and ordering are the operator's decisions from Step 9. Present them; do not choose them. Do not generate handoffs for parked or queued items until they are actually next.

When to run: only after the operator has agreed a kickoff stack in the Step 9 walkthrough. If Step 9 was declined or produced no kickoff stack, skip this step.

For each item in the agreed kickoff stack, write or refresh .oat/repo/pjm/handoffs/<BL-id>.md with:

• the backlog item reference — its ID and human-readable title and path (never a bare ID);
• the recommended project mode (oat-project-quick-start vs oat-project-new), including which artifacts (spec/design/plan) to pre-populate from existing research when it exists;
• authoritative input pointers (research directories, decision records, code paths);
• repo conventions and verification gates the item file does not restate;
• a close-out section requiring (a) the Backlog Lifecycle — oat backlog archive <id> — executed in the same PR that ships the item, and (b) deletion of the handoff file (git rm) in that same PR.

Staleness: if this alignment pass drops an item from the kickoff stack, delete its handoff (git rm .oat/repo/pjm/handoffs/<BL-id>.md) in the same pass rather than letting it drift.

Every backlog item reference in a handoff — like every reference in review output and alignment docs — pairs the ID with its human-readable title per the Reference Format Convention. No bare IDs.

Step 11: Offer External Plan Generation (Optional)

After the review flow concludes, offer:

Want to turn selected items from this backlog review into self-contained external implementation plans with oat-repo-improve?

If the operator accepts, invoke oat-repo-improve in backlog-review mode with the living review path. Also pass backlog/reviews/priority-alignment.md when it exists and was confirmed or refreshed during this run. The improve skill owns candidate selection, bounded live verification, plan generation under .oat/repo/reference/external-plans/, and backlog-item reverse links.

Do not generate external plans inside this skill. Do not assume the kickoff stack must become plans; present it as the recommended selection and let the operator adjust it. A generated external plan remains optional input to oat-project-import-plan, not a canonical OAT project plan.

Success Criteria

• Every active backlog item file has a value-effort rating with rationale
• Dependencies are explicitly mapped
• Parallel lanes and execution waves are actionable
• Roadmap alignment gaps are surfaced when roadmap input is present
• Output document follows the review template structure
• Living review is written to .oat/repo/pjm/backlog/reviews/backlog-and-roadmap-review.md (unless --output is explicitly overridden); dated snapshots, when emitted, live in the same backlog/reviews/ directory and never under .oat/repo/reviews/
• The operator is offered (but never forced into) a collaborative walkthrough that produces or updates backlog/reviews/priority-alignment.md; if the operator accepts, the file is written using the priority-alignment template and includes a Changelog entry for this pass; if the operator declines, no file is created or modified
• When a priority-alignment pass produces an agreed kickoff stack, one handoff per kickoff-stack item is written or refreshed under .oat/repo/pjm/handoffs/ (with item reference, recommended mode, input pointers, repo conventions/gates, and a close-out requiring the Backlog Lifecycle executed and the handoff deleted in the same shipping PR); handoffs for reprioritized-out items are deleted in the same pass; kickoff-stack membership, lane count, and ordering remain human decisions the skill presents rather than chooses
• The operator is offered an optional oat-repo-improve backlog-review <review> handoff; this skill never writes external plans itself
• Every user-facing reference to a backlog item pairs the ID with a human-readable title (per the Reference Format Convention)