review-plan

Files (15)

• SKILL.md
• guide.md
• consumer_fallout.py · scripts/
• consumer_fallout_analysis.py · scripts/
• final_gate_contract.py · scripts/
• plan_execution_gate.py · scripts/
• plan_template_check.py · scripts/
• review_round.py · scripts/
• review_round_support.py · scripts/
• task_graph_parser.py · scripts/
• task_graph_validation.py · scripts/
• bus_adapters_test.py · scripts/tests/
• final_gate_contract_test.py · scripts/tests/
• plan_execution_readiness_test.py · scripts/tests/
• verify_task_graph.py · scripts/

SKILL.md (first lines)

Resolve `SKILL_DIR` to the directory containing this loaded SKILL.md; keep the working directory in the target repository.
Review principles are in [guide.md](./guide.md); the SOT for macro judgment, task-graph safety, admissibility, and verdicts is
[plan-review-guide.md](../_bus/docs/guides/plan-review-guide.md). This file defines only the executable flow.
Input only needs to follow `docs/templates/plan-template.md`; it does not require the session that wrote the plan or any other private state.

Plans written before this migration remain historical inputs but are not
silently coerced into the new machine contract. The prologue identifies the
legacy status form and stops with one migration instruction: write a canonical
successor from `docs/templates/plan-template.md`, preserving the developer-owned goal,
non-goals, and decisions. `review-plan` stays read-only and never rewrites the
historical file itself.

```text
INPUT $ARGUMENTS =
  [<plan-file>] [--base <ref>] [--reviewer <lane>] [--devils-advocate]

DEFAULT reviewer = default (only when the prologue can select a lane unambiguously)

========== 1. READ-ONLY BOUNDARY ==========

MUST NOT:
  - modify the plan or repository files
  - check file checkboxes or rewrite plan state
  - git add / commit / checkout / stash / rebase

MAY:
  - write this skill's round artifacts under temp/review-plan/
  - run the read-only queries, tests, and builds needed to verify plan claims

========== 2. DETERMINISTIC PROLOGUE ==========

Run:
  python3 "$SKILL_DIR/../review-plan/scripts/review_round.py" \
    [<plan-file>] [--base <ref>] [--reviewer <lane>] [--devils-advocate]

IF exit != 0 AND output says multiple / named lanes make a bare invocation ambiguous:
  IF the developer already gave a lane, or said "use the previous lane" and this conversation has the REVIEWER of the last successful prologue:
    the value must exactly equal an existing lane listed by this FAIL; an approximate name must be confirmed with the developer first.
    Add `--reviewer <lane>` with that exact lane value and immediately rerun the prologue.
    Do not reply with only the lane name, and do not make another bare invocation.
  ELSE:
    reproduce stdout/stderr verbatim, ask the developer for the exact lane, then STOP.
ELSE IF exit != 0:
  reproduce stdout/stderr verbatim, then STOP.

IF NOTE says the state has entered review but this lane's history is lost:
  tell the developer this lane restarts under Round 1 full rules.

Capture:
  ROUND, MODE, POSTURE, REVIEWER, BRANCH, PLAN, STATE_DIR,
  SNAPSHOT, DIFF, PREV_REVIEWS, TRIAGE_LEDGER

========== 3. LOAD LOCKED CONTEXT ==========

Read($SKILL_DIR/../review-plan/guide.md) completely
Read($SKILL_DIR/../_bus/docs/guides/plan-review-guide.md) completely
Read($SKILL_DIR/../_bus/docs/guides/architecture-principles.md) completely
Read($SKILL_DIR/../_bus/docs/guides/consumer-fallout-format.md) completely
plan = Read(PLAN) completely

The goal, non-goals, archived decisions, and one-shot workflow are locked inputs; do not rewrite, expand, or overturn them.
Plan content that violates the locked inputs may become a finding. Only when new evidence disproves the factual premise of a decision
may you output a one-line "decision-premise challenge" for the developer to adjudicate.

IF TRIAGE_LEDGER != none:
  decided = Read every comma-separated TRIAGE_LEDGER, oldest to newest
  for the same location + semantic root cause, the newest disposition wins:
    rejected -> do not re-raise, unless new evidence disproves its factual premise
    applied  -> verify only the repair; carry forward only an incorrect repair or a newly introduced problem
    flagged  -> do not duplicate as a finding

========== 4. POSTURE ==========

IF POSTURE == devils-advocate:
  actively falsify as defined by guide.md, without changing scope, lane, MODE, or the evidence standard.
ELSE:
  use the standard posture.

========== 5. MODE = full ==========

IF MODE == full:
  first read the material the plan references and the relevant source,
  independently establish the current state, then verify the plan's claims; the plan's paraphrase itself is never evidence.
  fallout = `<dirname(SNAPSHOT)>/consumer-fallout.json`
  Run `python3 "$SKILL_DIR/../review-plan/scripts/consumer_fallout.py" --plan <PLAN> --output <fallout>`.
  Consume only stdout's per-task, high-confidence unresolved summary; do not load the complete artifact into context wholesale.
  When `omitted_unresolved_count > 0`, gather evidence only in the relevant task bucket; a candidate must be verified as closed on file contract, owner,
  and gate, or explicitly excluded.

  IF runtime supports subagent dispatch:
    the user invoking this skill explicitly authorizes read-only narrow fan-out for this round.
    Use the fewest groups necessary for the plan's size:
      architecture = multiple purposes, boundaries, dependency direction, duplicate mechanisms, implicit decisions
      completeness = missing files/tasks/tests, internal contradictions, mismatches with source facts
      task-graph safety narrow subagent =
        dependencies, isolation, producer/consumer, hidden semantic cycles, false edges, false independent acceptance
      evidence = ambiguity, test scenarios, whether validation commands truly cover the goal, other macro problems admitted under the strict bar

    Every **dimension-group** subagent must (except the fresh-eyes subagent, see below):
      - Read($SKILL_DIR/../_bus/docs/guides/plan-review-guide.md) and docs/guides/architecture-principles.md
      - Read(PLAN) completely plus the first-party source/SOT its group needs
      - review only its assigned dimensions, read-only, never modifying the repo
      - honor the locked goals, non-goals, archived decisions, and one-shot workflow
      - make macro judgments only and return raw candidates:
        plan location / observation / evidence / impact / optional remediation

    **A fresh-eyes subagent must also be dispatched.** It is this round's source of viewpoint diversity, not an optional supplement:
    the groups above all start from the same checklist and find what the checklist expects; problems the checklist cannot name
    are only stumbled upon by an agent that never read the checklist.
    The ground truth it receives must be **verbatim identical** to the other groups' — the same PLAN snapshot, the same goal /
    non-goals / archived decisions; the only allowed difference is "no checklist".
    It **must not** read plan-review-guide.md, architecture-principles.md, the dimension lists, or any prior review: an agent that has read the checklist
    is no longer fresh eyes; it will confirm the checklist item by item instead of reading the plan.
    §1 READ-ONLY BOUNDARY and the locked inputs apply to it in full, not relaxed by a single word.
    Every source produces candidates only; none writes its own review.md.
    The main agent returns to first-party evidence, verifies each candidate, deduplicates by location + semantic root cause,
    discards nitpicks and items already decided in triage, then closes every subagent of this round.
  ELSE:
    the main agent covers every dimension serially.

From asura1234/bus, Apache-2.0.

More from asura1234/bus