tomevault-io 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:outlinecommand - 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:
- What problem are we solving?
- What does success look like?
- What constraints exist?
- 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
Converted and distributed by TomeVault — claim your Tome and manage your conversions.