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:

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:

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

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