refactor: default /ba:plan to decisions, gate code behind a shape label#30
Draft
azevedo wants to merge 9 commits into
Draft
refactor: default /ba:plan to decisions, gate code behind a shape label#30azevedo wants to merge 9 commits into
azevedo wants to merge 9 commits into
Conversation
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>
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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
/ba:planno 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:plandocs 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-planrestructure — deferred; the hybrid changes its inputs, so its fate is decided after this lands.🤖 Generated with Claude Code