plan

<!-- plan-anti-bypass-protocol:start -->

Anti-bypass protocol (load-bearing — especially Grok Build)

You are the planning orchestrator. Whether entered from /brainstorm, /one-shot Step 1, or direct /plan:

• FORBIDDEN: Implementing product code (Write/Edit/Shell) before the plan artifact and tasks are written.
• FORBIDDEN: Ending after saving plans/ + tasks.md without invoking /work — the plan is a checkpoint, not a deliverable.
• REQUIRED (Grok Build): Invoke /work <plan-path> (or /deepen-plan when the plan requests it) via slash command — never substitute ad-hoc implementation.
• Harness adapter: plugins/soleur/lib/harness.ts — Grok uses /work, /deepen-plan; Claude uses Skill tool.

See plugins/soleur/lib/workflow-fidelity.ts (HANDOFF_SKILLS, mandatorySuccessors('plan')). <!-- plan-anti-bypass-protocol:end -->

Create a plan for a new feature or bug fix

Introduction

Note: The current year is 2026. Use this when dating plans and searching for recent documentation.

Transform feature descriptions, bug reports, or improvement ideas into well-structured markdown files issues that follow project conventions and best practices. This command provides flexible detail levels to match your needs.

Feature Description

<feature_description> #$ARGUMENTS </feature_description>

If the feature description above is empty, ask the user: "What would you like to plan? Please describe the feature, bug fix, or improvement you have in mind."

Do not proceed until you have a clear feature description from the user.

0. Load Knowledge Base Context (if exists)

Load project conventions:

# Load project conventions
if [[ -f "CLAUDE.md" ]]; then
  cat CLAUDE.md
fi

Branch safety check (defense-in-depth): Run git branch --show-current. If the result is main or master, abort immediately with: "Error: plan cannot run on main/master. Checkout a feature branch first." This check fires in all modes as defense-in-depth alongside PreToolUse hooks -- it fires even if hooks are unavailable (e.g., in CI).

Check for knowledge-base directory and load context:

Check if knowledge-base/ directory exists. If it does:

1. Run git branch --show-current to get the current branch name
2. If the branch starts with feat-, read knowledge-base/project/specs/<branch-name>/spec.md if it exists

If knowledge-base/ exists:

1. Read CLAUDE.md if it exists - apply project conventions during planning
2. If # Project Constitution heading is NOT already in context, read knowledge-base/project/constitution.md - use principles to guide planning decisions. Skip if already loaded (e.g., from a preceding /soleur:brainstorm).
3. Detect feature from current branch (feat-<name> pattern)
4. Read knowledge-base/project/specs/feat-<name>/spec.md if it exists - use as planning input
5. Announce: "Loaded constitution and spec for feat-<name>"

If knowledge-base/ does NOT exist:

• Continue with standard planning flow

0.5. Idea Refinement

Check for brainstorm output first:

Before asking questions, look for recent brainstorm documents in knowledge-base/project/brainstorms/ that match this feature:

ls -la knowledge-base/project/brainstorms/*.md 2>/dev/null | head -10

Relevance criteria: A brainstorm is relevant if:

• The topic (from filename or YAML frontmatter) semantically matches the feature description
• Created within the last 14 days
• If multiple candidates match, use the most recent one

If a relevant brainstorm exists:

1. Read the brainstorm document
2. Announce: "Found brainstorm from [date]: [topic]. Using as context for planning."
3. Extract key decisions, chosen approach, and open questions
4. Skip the idea refinement questions below - the brainstorm already answered WHAT to build
5. Proceed to Phase 1 -- all sub-phases still apply (1, 1.5, 1.5b, 1.6). Having a brainstorm skips idea refinement only, not community discovery or research.

If multiple brainstorms could match: Use AskUserQuestion tool to ask which brainstorm to use, or whether to proceed without one.

If no brainstorm found (or not relevant), run idea refinement:

Refine the idea through collaborative dialogue using the AskUserQuestion tool:

• Ask questions one at a time to understand the idea fully
• Prefer multiple choice questions when natural options exist
• Focus on understanding: purpose, constraints and success criteria
• Directional ambiguity gate: If the task involves merging, moving, or restructuring (A into B vs B into A), explicitly confirm the direction with the user before proceeding -- even in pipeline mode. Code evidence can be wrong (see learning: 2026-03-17-planning-direction-confirmation-required)
• Continue until the idea is clear OR user says "proceed"

Gather signals for research decision. During refinement, note:

• User's familiarity: Do they know the codebase patterns? Are they pointing to examples?
• User's intent: Speed vs thoroughness? Exploration vs execution?
• Topic risk: Security, payments, external APIs warrant more caution
• Uncertainty level: Is the approach clear or open-ended?

Skip option: If the feature description is already detailed, offer: "Your description is clear. Should I proceed with research, or would you like to refine it further?"

0.6. Pre-Research Premise Validation (Always)

Run BEFORE spawning any research (Phase 1) — research and downstream phases are expensive, and building a plan atop a stale premise wastes all of it. brainstorm Phase 1.1 does this validation when a brainstorm precedes plan, but plan is frequently entered directly (including the one-shot → plan path that skips brainstorm), so the cheap probe must also live here. This is distinct from Phase 1.7 reconciliation (which checks spec claims AFTER research returns) — this gate fires before research is even dispatched.

This also covers your own option-bounding capability claims — not just cited references. Before asserting that a repo tool/skill/script "only does X" or "can't do Y" to bound the plan's options, grep/read it first or phrase it as a question (hr-verify-repo-capability-claim-before-assert).

For every issue, blocker, dependency, or prior-art artifact the feature description cites by reference, verify it still holds:

1. Cited GitHub issues / PRs (#N, Closes #N, "blocked by #N", "follow-up to #N"): run gh issue view <N> --json state,title,closedByPullRequestsReferences and gh pr view <N> --json state,merged where applicable. If a blocker is already closed/merged, or the issue this plan targets is already closed by a merged PR, the premise is stale — surface via AskUserQuestion ("Issue #N appears already resolved by PR #M. Re-scope, or close as done?") rather than planning against it.
2. Cited file/symbol/migration paths (a function, route, component, or migration the plan assumes exists): confirm with git show origin/main:<path> or git grep -n "<symbol>" origin/main. If the cited artifact does not exist on origin/main, the premise ("fix the bug in X") may really be "X was never built" — flag it; the plan's shape changes from fix to build.
3. "UI exists but is broken" claims: distinguish broken behavior from never-built. If the description asserts a UI/endpoint misbehaves, confirm the route/component is actually present (git grep) before planning a behavioral fix — a silently-absent feature needs a build plan, not a patch.
4. **Proposed mechanism vs. the ADR corpus** (the feature names HOW to do it — a frontmatter flip, a new table, a polling cron, a config tier): grep knowledge-base/engineering/architecture/decisions/ for the mechanism's keywords (not the cited issue number — issues don't know what an ADR decided) and read any hit's ## Decision + ## Alternatives Considered. A mechanism sitting in an ADR's rejected-alternativ