elb-pr/brain-jam-plan

Brain-Jam Planning Methodology

Overview

Planning is an iterative conversation, not a production line. The human stays in the loop at every phase.

"Go back and forth with Claude until I like its plan. A good plan is really important." — Boris

Core principle: Understand before solving. Ask before assuming. Recommend but let user decide.

Trigger Symptoms

Use this skill when:

• Running the claudikins-kernel:outline command
• Requirements are unclear or keep changing
• Multiple valid approaches exist and you can't choose
• User wants involvement in decisions (not just receive a plan)
• Previous plans failed due to missed requirements
• Scope creep is a concern
• You're tempted to just start coding without a plan

The Brain-Jam Process

Phase 1: Requirements Gathering

One question at a time. Wait for the answer.

Key questions to answer:

1. What problem are we solving?
2. What does success look like?
3. What constraints exist?
4. What's explicitly OUT of scope?

Use AskUserQuestion with specific options — never open-ended unless necessary.

Phase 2: Context Building

Before proposing solutions, understand the landscape:

• What exists already in the codebase?
• What patterns should we follow?
• What dependencies apply?
• What has been tried before?

Phase 3: Approach Generation

Generate 2-3 distinct approaches. Each must include:

| Element | Purpose | | ------- | --------------------- | | Summary | 1-2 sentence overview | | Pros | Clear benefits | | Cons | Honest trade-offs | | Effort | low / medium / high | | Risk | low / medium / high |

Always recommend one with reasoning. See approach-template.md.

Phase 4: Section-by-Section Drafting

Draft one section at a time. Get approval before moving on.

Never batch approvals — each checkpoint is a chance to course-correct.

Non-Negotiables

These rules have no exceptions:

One question at a time.

• Not "let me ask a few things"
• Not "quick questions"
• One question. Wait. Process answer. Next question.

Always present 2-3 approaches.

• Not "here's what I recommend"
• Not "the obvious choice is..."
• Present options. Recommend one. User decides.

Checkpoint before proceeding.

• Not "I'll assume that's fine"
• Not "continuing unless you object"
• Explicit approval. "Does this look right?" Wait for yes.

Never fabricate research.

• Not "based on my understanding"
• Not "typically in codebases like this"
• If you don't know, research or ask. Don't invent.

Plan Quality Criteria

A good plan has:

• [ ] Clear problem statement
• [ ] Explicit scope boundaries (IN and OUT)
• [ ] Measurable success criteria
• [ ] Task breakdown with dependencies
• [ ] Risk identification and mitigations
• [ ] Verification checklist

See plan-checklist.md for full verification.

Output Format

Plans must include machine-readable task markers for claudikins-kernel:execute compatibility:

<!-- EXECUTION_TASKS_START -->

| #   | Task          | Files                | Deps | Batch |
| --- | ------------- | -------------------- | ---- | ----- |
| 1   | Create schema | prisma/schema.prisma | -    | 1     |
| 2   | Add service   | src/services/user.ts | 1    | 1     |

<!-- EXECUTION_TASKS_END -->

See plan-format.md for complete structure.

Anti-Patterns

Don't do these:

• Batching multiple questions together
• Proposing solutions before understanding requirements
• Presenting only one approach
• Skipping the verification checklist
• Continuing without explicit approval at checkpoints
• Fabricating research findings when data is sparse

Rationalizations to Resist

Agents under pressure find excuses. These are all violations:

| Excuse | Reality | | ----------------------------------------------------- | ------------------------------------------------------------- | | "I'll batch questions to save time" | Batching causes missed requirements. One at a time. | | "User knows what they want, skip brain-jam" | Assumptions cause rework. Gather requirements explicitly. | | "I'll propose solutions while gathering requirements" | Solutions bias requirements. Understand first, solve second. | | "User implied preference, don't need alternatives" | Implied ≠ decided. Always present 2-3 options. | | "This is simple, don't need checkpoints" | Simple plans still fail. Checkpoints catch errors early. | | "I already know the right approach" | Your confidence isn't approval. User decides. | | "Alternatives will confuse them" | Confusion means requirements are unclear. Clarify. | | "I'll get approval for multiple sections at once" | Batched approvals hide problems. One section, one checkpoint. |

All of these mean: Follow the methodology. No shortcuts.

Red Flags — STOP and Reassess

If you're thinking any of these, you're about to violate the methodology:

• "Let me just quickly..."
• "The user probably wants..."
• "This is obvious, I don't need to ask"
• "I'll come back to requirements later"
• "One approach is clearly best"
• "They already approved something similar"
• "Checkpoints slow things down"
• "I know what they meant"

All of these mean: STOP. Return to methodology. Ask, don't assume.

Edge Case Handling

| Situation | Reference | | -------------------------------- | ----------------------------------------------------------------------------- | | Context collapse mid-plan | session-collapse-recovery.md | | Endless iteration loop | iteration-limits.md | | Research taking too long | research-timeouts.md | | Approaches contradict each other | approach-conflict-resolution.md | | User abandons plan | plan-abandonment-cleanup.md | | Requirements keep changing | requirement-stability.md |

References

• plan-checklist.md — Verification checklist
• approach-template.md — How to present options
• plan-format.md — Output structure for claudikins-kernel:execute
• iteration-limits.md — When to stop iterating
• requirement-stability.md — Scope creep detection
• approach-conflict-resolution.md — Conflicting approaches
• session-collapse-recovery.md — Context collapse handling
• research-timeouts.md — Timeout handling
• plan-abandonment-cleanup.md — Cleanup procedures