Skip to content

feat(vibe): Add cl-execute plan-review prompt and cost scaling gate - #298

Merged
shafty023 merged 2 commits into
mainfrom
feat/cl-execute-plan-review-architecture
Oct 16, 2026
Merged

shafty023 merged 2 commits into
mainfrom
feat/cl-execute-plan-review-architecture

Conversation

@shafty023

@shafty023 shafty023 commented Oct 16, 2026 •

Copy link
Copy Markdown
Collaborator

Purpose

cl-execute plans kept clearing review with mechanisms nobody had weighed against what already exists. I ran it blind on one historical ticket (three planner runs, then two rounds of plan-review A/B testing) and saw the same failures each time:

  • The planner built the mechanism the ticket named because the ticket named it, even though a cheaper existing channel was already in the repo.
  • A ticket's "Decisions" section was read as settled, and a newer, uncited ticket was taken to supersede an earlier explicit ruling.
  • The repo's instruction-inflation and manufactured-ambiguity rules were cited as the reason not to raise consent and mechanism questions.
  • Plan-review findings the reviewer marked as needing a human were resolved by the planner instead.

The plan-review prompt added here won the A/B test: it blocked an install-scaled design in 3 of 3 reviews, against 0 of 3 for the baseline prompt, and it did not block a sound design in the control.

What changed

  • New references/plan-review-prompt.md. Step 20 now passes it verbatim to the single plan reviewer, followed by the plan path, ticket, PRD slugs and a private path for the review file. Only two parts differ from the tested text: the review is written to the ticket's private evidence directory instead of /tmp, and the worker section gives both the Claude Code and the Codex (spawn_agent, send_input) forms, with a support lane doing the reads itself since it never delegates.
  • Step 20: a finding the reviewer lists under HUMAN DECISIONS can't be resolved, downgraded or absorbed by the worker. Each one becomes a numbered decision returned with MANUAL_INTERVENTION_REQUIRED, and the worker can add its own view beside it. The exactly-one-review rule is unchanged.
  • Step 13: only the outcome a ticket asks for is binding. If the ticket names a mechanism and it's dominated, the plan keeps the outcome and brings the mechanism choice to the human as one decision. It never swaps or builds it silently. Raising that decision is stated to be neither instruction inflation nor manufactured ambiguity.
  • New Cost Scaling section: periodic or cross-surface work needs a ### Cost Scaling table (Option, Cost scales with, Per-device idle cost, At 10x / 100x, Existing mechanism reused) with at least two rows, and one row has to name an existing mechanism. check-plan.mjs enforces it when prose outside code fences uses a conservative keyword set. --no-periodic waives it, and the waiver is on the record.
  • Readiness gate gains Decision provenance. SKILL.md gains a Discovery Routes row for existing channels between two surfaces.
  • vibe 1.0.46 to 1.0.47, CHANGELOG entry.

Files changed

  • plugins/vibe/skills/cl-execute/references/plan-review-prompt.md (new)
  • plugins/vibe/skills/cl-execute/references/planning-and-gates.md
  • plugins/vibe/skills/cl-execute/SKILL.md
  • plugins/vibe/skills/cl-execute/scripts/check-plan.mjs, check-plan.test.mjs
  • plugins/vibe/.claude-plugin/plugin.json, plugins/vibe/.codex-plugin/plugin.json
  • CHANGELOG.md

Commands run

node --test <every plugins/**/*.test.mjs file, as CI does>   # 392 pass, 0 fail
uv run pytest plugins/vibe -q                               # 243 passed
cd tools/plugin-manifests && npm ci && npm test             # 6 passed
node check-plan.mjs <sample plans> --template <template>    # polling with no table: exit 1; one-row table: exit 1; two rows with an existing mechanism: exit 0; --no-periodic: exit 0

The cl-sweep skill-contract test still passes unchanged; the pinned step 13 and step 20 sentences were kept word for word. New linter tests cover: table present, table missing, one-row table, no existing mechanism, missing column, no trigger, keywords inside code fences, and --no-periodic.

- Ship the plan-review prompt as references/plan-review-prompt.md and
  pass it verbatim to the single plan reviewer, with a private review
  path and Claude Code and Codex worker forms.
- Carry every reviewer HUMAN DECISIONS item into the numbered decisions
  returned with MANUAL_INTERVENTION_REQUIRED.
- Treat a mechanism a ticket names as a proposal; a dominated one goes
  to the human as one decision instead of being built or swapped.
- Add a Decision provenance readiness item and a Discovery Routes row
  for existing channels between surfaces.
- Require a Cost Scaling table for periodic or cross-surface work and
  enforce it in check-plan.mjs, with a --no-periodic waiver.
- Release vibe 1.0.46.

Testing: node --test over every plugin test file (392 pass), vibe
pytest (235 pass), check-plan.mjs run against sample plans.
Risks: The keyword trigger can fire on plans that only mention a
socket or feed; --no-periodic waives it on the record.
@shafty023
shafty023 merged commit c829f66 into main Oct 16, 2026
10 checks passed
@shafty023
shafty023 deleted the feat/cl-execute-plan-review-architecture branch October 16, 2026 02:25
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant