STAR: Skill for Codex

Research Plan Reviser

Invocation: star-plan-reviser PLAN_NAME [DESCRIPTION]. Resolve the plan first. Natural language that clearly gives up or revives the direction selects a drop or a revival and supplies its reason; otherwise run the evidence review. It may also approve named revision items. A request to review, audit, or read the report without changes stops after the report and does not enter revision Q&A. With no settled target, list candidates and ask.

Shared conventions. Follow docs/mds/star-workflow/research-workflow-conventions.md for scope, authority, .env controls (STAR_LANG, INVOLVE, STAR_*_MODEL), runtime, language and provenance. Its opening loading rule selects the sections and localized resources this task needs.

After resolving the target and the drop, revival, or review path, run scripts/scan.sh --slim; use its plan frontmatter, sub-plan indexes, and run-log frontmatter as raw scope input, then read the target and governing references at the evidence step. If it fails, read the plans directly and report the fallback.

Passing a tier model. Before delegation, read conventions §6 (scope and independent context), §10.8 (tier selection), and the current harness entry in §13 (model and depth controls).

Role

Take one plan node, audit its intent against execution evidence, and revise the plan in place only for changes the user has already directed or accepts from the visible candidate list. star-flow-status is the shallow whole-tree view; this skill is the deep single-plan audit.

Revise text; do not re-run experiments, re-decompose subtrees, or re-derive strategy from scratch.

Core Principles

1. Evidence before opinion. Every review claim carries an evidence pointer (file path, log line, command output). A log's self-reported done is not completion — corroborate it against artifacts on disk, re-running cheap checks where pivotal; never launch heavy experiments (conventions §2's STOP line applies here too). This applies the project's Verification rule (AGENTS.md §11) to the plan itself. Rules: references/review_spec.md.
2. Collect wide; judgment stays with the main agent. Delegate collection whenever bounded, independent, read-only inspection of several runs or artifact sets materially helps; when it does, dispatch a read-only sub-agent on the READ tier's model (conventions §10.8), where the harness can name one. Any delegate follows the collector format in references/review_spec.md and never writes or proposes revisions. Synthesis and judgment stay with the main agent.
3. The user owns every change. Findings become numbered revision candidates. Apply any named changes already authorized; put the rest on the page and ask once under conventions §7.13. Every write must trace to an explicit directive or a candidate accepted from that visible list.
4. Revise in place, leave a trail. Approved edits go into the original <prefix>_<slug>_plan.md; never fork _v2 copies (a duplicate prefix breaks the tree status/decomposer/executor parse). Each session appends one ## Revision History entry (date, per-change one-liners with evidence, report path) and bumps updated; older versions live in git.
5. Stay inside the family's write discipline. Never renumber prefixes; never touch EXEC_PLAN.md / EXEC_LOG.md (the executor's); structural re-shaping (add/remove sub-plans, redraw the dependency graph) routes to star-plan-decomposer, research-question or method pivots to star-plan-coach — while the target's outline lines, units not yet expanded into files (conventions §0), are text and stay local candidates. Boundaries: references/revision_rules.md.
6. Knock-on effects. A revision can invalidate work built on the old text. Point out reverse depends_on edges and derived children before asking for changes (report §6); sync the parent's ## Sub-plans one-liner when the objective line changes; the bumped updated lets star-flow-status show staleness downstream.