Skip to content

refactor: default /ba:plan to decisions, gate code behind a shape label#30

Draft
azevedo wants to merge 9 commits into
mainfrom
claude/plan-verbosity-research-3al1it
Draft

refactor: default /ba:plan to decisions, gate code behind a shape label#30
azevedo wants to merge 9 commits into
mainfrom
claude/plan-verbosity-research-3al1it

Conversation

@azevedo

@azevedo azevedo commented Jun 14, 2026

Copy link
Copy Markdown
Owner

What

/ba:plan no longer mandates literal implementation code in every plan. Plans now default to decisions — approach, exact file paths, patterns to follow, pseudo-code for shape, and test scenarios. A real code block is permitted only under a **Code-shape decision:** <why> label, where the code's shape is the design decision.

This reframes plan code from rework-prevention (unmeasured, and already half-disabled by /ba:execute) to design validation — a forcing function applied precisely where the design is non-obvious.

Why

Reviewing /ba:plan docs is expensive because the implementation body — code plus comments — is 60–80% of every painful plan, not the framing sections (consolidated verbosity research on this branch). A provenance check found the keep-code rule is inherited ce-plan heritage that ce itself reversed six days after our fork. Dropping it where it doesn't pay removes the bulk of review cost without losing the one place code earns its keep.

The contract change (the ~45 lines that matter)

The source change is small; most of this diff is the research → brainstorm → plan trail that motivates it.

  • plan.md — templates and "Key rules" default to decisions; the **Code-shape decision:** trigger ships with a positive/negative example pair + a when-unsure tiebreaker; Step 0 and the rule anchor code-bearing blocks to the brainstorm's ## Locked Design.
  • execute.md — Step 2b implements to the plan's decisions, while any literal code block stays binding-when-present (backward-safe: pre-change plans, which are all literal code, execute unchanged). Step 1.5b gains a literal-vs-pseudo discriminator so the scope-tripwire isn't biased by pseudo-code.
  • slice.md — same discriminator + pre-change backward-compat in LoC sizing.
  • README.md, CLAUDE.md (label-sync convention across the four files), plugin.json (0.23.0 → 0.24.0).

Backward compatibility

Plans already on disk are full literal code with no labels. The rule "any literal code block is binding when present" means they execute and slice exactly as before — no version flag, no migration.

Out of scope / deferred

  • /ba:review-plan restructure — deferred; the hybrid changes its inputs, so its fate is decided after this lands.
  • The internal code-repo research pass (company data) is not included — kept local.
  • Manual validation (re-render a STANDARD + COMPREHENSIVE plan under the new rule) is noted in the plan but not yet run.

🤖 Generated with Claude Code

claude and others added 7 commits June 13, 2026 21:26
Evidence-based diagnosis of where reviewing a plan doc costs too much.
Volume map across all 24 plan docs by detail level and section (code vs
prose split); review-value inferred from the user's keep-code criterion,
the hand-built HTML companion workaround (PR #15), and the existing
plan-iteration LoC gate. Finds the cost is the template's framing tax at
COMPREHENSIVE (altitude redundancy, intra-doc and brainstorm->plan
duplication), not the code blocks. Proposes a restructure + demotion
direction with a line target, no code or scope content removed.

https://claude.ai/code/session_014UWUxvppgQFWuYRTFz8ssu
Add a scope banner naming what this pass could not see (real code repo,
larger plan corpus, execution transcripts, PR review comments) so the
planned code-repo pass and later consolidation know which findings are
measured (volume) vs hypotheses to validate (review-value).

https://claude.ai/code/session_014UWUxvppgQFWuYRTFz8ssu
Self-contained prompt to run the second (code-repo) plan-verbosity pass:
bakes in the fixed problem/scope, points at behavioral evidence
(transcripts + PR review comments) the md-only pass lacked, lists the
prior hypotheses to validate or overturn, and instructs pushing a new
file to this branch for consolidation.

https://claude.ai/code/session_014UWUxvppgQFWuYRTFz8ssu
…gated plan code

research: sanitized consolidation of the md-only and code-repo plan-verbosity passes into one diagnosis — combined volume map, reconciled review-value (corroborated/overturned/unresolved), re-derived per-level targets, and fix direction.

brainstorm: justification-gated hybrid for /ba:plan code — decisions-by-default (approach, exact file paths, patterns, test scenarios); real code only behind a Code-shape decision label, anchored to brainstorm Locked Design. Reframes plan code as design validation, not rework-prevention; review-plan restructure deferred.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…shape decision label

Invert plan.md's keep-code mandate: templates and Key rules now default to
decisions + pseudo-code; a literal code block is permitted only under a
**Code-shape decision:** label. Wire Step 0 + Key rules to the brainstorm's
## Locked Design as the anchor for code-bearing blocks.

Plan: docs/plans/2026-06-16-refactor-plan-code-justification-gate-plan.md

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…ward-safe

Soften execute Step 2b to implement-to-decisions while keeping any literal
code block binding-when-present (backward-safe for pre-change plans). Add a
literal-vs-pseudo discriminator to Step 1.5b and slice LoC counting (label-
preceded = literal; unlabeled fence = pseudo -> estimate; no labels anywhere
= treat all fences as literal). Reconcile the plan-is-authority guideline.

Plan: docs/plans/2026-06-16-refactor-plan-code-justification-gate-plan.md

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…on, bump version

Soften README /ba:plan description (code -> decisions + labeled code-shape),
add the cross-file label-sync convention to CLAUDE.md (plan/execute/slice/
README mirrors), bump plugin.json 0.23.0 -> 0.24.0, and land the executed plan.

Plan: docs/plans/2026-06-16-refactor-plan-code-justification-gate-plan.md

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@azevedo azevedo changed the title Plan-verbosity research + justification-gated plan-code direction refactor: default /ba:plan to decisions, gate code behind a shape label Jun 16, 2026
azevedo-remote and others added 2 commits June 16, 2026 16:42
Resolve two High internal contradictions and four Medium consistency nits
from post-implementation review:
- execute.md Step 2b: reference Step 1.5b's literal/pseudo classification
  instead of implying every fence binds.
- slice.md detail-level bullets: defer to the LoC Counting Rules instead of
  'count lines in code fences' (which contradicted the literal-only rule).
- execute.md Step 1.5b: render the 3-case classification as a list.
- plan.md template placeholders: carry the <why> suffix.
- slice.md: move the mirror pointer to a maintainer HTML comment.
- CLAUDE.md: name the template placeholders as label mirror targets.

Plan: docs/plans/2026-06-16-refactor-plan-code-justification-gate-plan.md

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The Important Guidelines summary mentioned the **Code-shape decision:** label
but omitted the when-unsure tiebreaker stated in the Key-rules body (line 434).
Append a short pointer so the quick-reference matches the body. Closes the one
finding suppressed by the review's confidence gate.

Plan: docs/plans/2026-06-16-refactor-plan-code-justification-gate-plan.md

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
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.

3 participants