Planning Skill

This skill guides you through collaborative task planning with the user.

When to Use This Skill

Use this skill when:

• •User describes a new feature or project to implement
• •User asks to plan or break down work
• •Starting a new feature branch with no existing tasks
• •User says something like "I need to add...", "Let's build...", "Help me implement..."

Planning Dialogue Process

Step 1: Understand Requirements

Ask clarifying questions to fully understand what needs to be built:

• •What is the goal or purpose of this feature?
• •Who are the users? What problem does this solve?
• •Are there specific requirements, constraints, or preferences?
• •Are there existing patterns in the codebase to follow?
• •What does "done" look like?

Take time to understand before proposing tasks. Don't rush to decomposition.

Step 2: Propose Task Breakdown

Based on the requirements, propose a breakdown of the work into discrete tasks.

Task Sizing Guidelines:

• •Each task should represent one logical, reviewable change
• •Tasks should be small enough to review in one sitting (typically 30-60 minutes of work)
• •A task is too big if it touches multiple subsystems or has multiple concerns
• •A task is too small if it's a single line change with no context

Good Task Examples:

• •"Add ThemeContext provider with light/dark state"
• •"Create color palette constants for dark mode"
• •"Update Button component to use theme colors"

Bad Task Examples:

• •"Implement entire dark mode feature" (too big, not reviewable)
• •"Change button color to #333" (too small, no context)

Present the breakdown to the user:

Here's how I'd break this down:

1. [Task Title] - [Brief description]
2. [Task Title] - [Brief description]
   - Depends on: Task 1
3. [Task Title] - [Brief description]
   - Depends on: Task 2

Does this breakdown make sense? Any tasks to add, remove, or split?

Step 3: Refine with User Feedback

Be collaborative, not dictatorial. The user knows their codebase and priorities.

• •If user suggests changes, adjust the breakdown accordingly
• •If user identifies missing work, add new tasks
• •If user thinks a task is too big, split it further
• •If user thinks tasks are too granular, combine them

Keep iterating until user approves the plan.

Step 4: Create Tasks

Once the user approves, create tasks using the tools:

First, call dshearer.misatay/initTaskSystem to ensure the task system is initialized in the workspace. This is safe to call even if already initialized.

For each task in the approved breakdown:

1. •

   Create the task using dshearer.misatay/createTask:

   • •title: "Task Title"
   • •description: "Detailed description of what needs to be done, why, and any relevant context"
   • •status: "ready"
   • •Returns: task ID (e.g., "bd-abc1")
2. •

   Add dependencies if needed using dshearer.misatay/addDependency:

   • •childTaskId: The task that must wait
   • •parentTaskId: The task that must be completed first
   • •Only add when task B genuinely requires task A to be done first

Dependency Guidelines:

• •Add dependency when task B requires task A's code to work
• •Add dependency when task B logically follows task A (e.g., tests after implementation)
• •Don't add dependency if tasks are independent and can be done in any order
• •Don't over-constrain - allow parallelization when possible

Step 5: Commit Planning State

After creating all tasks, call dshearer.misatay/backendInfo to check the backend type.

If persistsToFiles is true: Commit the task state to Git:

git add -A
git commit -m "Plan feature: <feature name>"

This creates a commit containing the .beads/issues.jsonl changes from planning.

If persistsToFiles is false: Skip the commit — in-memory tasks have no files to stage. Just confirm that tasks were created successfully.

Step 6: Confirm Completion

After creating the plan (and committing if applicable):

1. •

   List the created tasks to confirm they're in the system using dshearer.misatay/listTasks

2. •

   Present a summary to the user:

   code

   ✅ Created 5 tasks for dark mode feature:
   
   - bd-abc1: Add ThemeContext provider
   - bd-abc2: Create color palette (depends on bd-abc1)
   - bd-abc3: Update Button component (depends on bd-abc2)
   - bd-abc4: Update Header component (depends on bd-abc2)
   - bd-abc5: Add dark mode toggle (depends on bd-abc3, bd-abc4)
   
   Ready to start implementing? I'll begin with task bd-abc1.
   

Planning Completion Criteria

Planning is complete when:

✅ All tasks have been created with clear titles and descriptions
✅ Dependencies are established where needed
✅ User has approved the breakdown
✅ Task list has been confirmed via listTasks()
✅ Planning state has been committed to Git

After planning is complete:

• •Switch to execution skill to start implementing tasks
• •Or wait for user to review the plan and ask you to proceed

Examples

Example 1: Simple Feature

User: "Add a loading spinner to the submit button"

You: "I can help with that! A few questions:

- Should the spinner appear while the form is submitting, then disappear?
- Do you have a preferred spinner component or library, or should I create one?
- Should the button be disabled while loading?"

User: "Yes to all, and we use react-spinners library"

You: "Perfect! Here's how I'd break this down:

1. Add loading state to submit handler
2. Update Button component to accept isLoading prop
3. Integrate Spinner from react-spinners into Button
4. Add disabled state when loading

This should be 3-4 small commits. Does this work?"

User: "Looks good, but combine tasks 2 and 3"

You: "Got it! Updated breakdown:

1. Add loading state to submit handler  
2. Update Button component with isLoading prop and Spinner
3. Add disabled state when loading (depends on task 2)

Should I create these tasks?"

User: "Yes"

You: [Creates tasks using createTask and addDependency tools]

"✅ Created 3 tasks. Ready to start with task 1?"

Example 2: Complex Feature Requiring Clarification

User: "Add user authentication"

You: "Authentication is a broad feature! Let me understand the requirements:

- What type of auth? (Email/password, OAuth, magic links, etc.)
- Do you have a backend API, or do we need to set that up too?
- What pages/routes should be protected?
- Should we store sessions in localStorage, cookies, or something else?
- Any existing auth library you prefer (like Auth0, Supabase, Firebase)?"

User: "Email/password, we have a backend API at /api/auth, protect the /dashboard route, use localStorage, no external library"

You: "Thanks! Here's my proposed breakdown:

1. Create AuthContext provider with login/logout/state
2. Add login form component
3. Add API integration for login endpoint
4. Add protected route wrapper for /dashboard
5. Add logout functionality
6. Add token storage in localStorage
7. Add auto-login on page load (check stored token)

Dependencies:
- Tasks 2, 3, 4, 6 depend on task 1 (context must exist first)
- Task 7 depends on task 6 (token storage must work first)

This gives us 7 reviewable commits. Thoughts?"

User: "Looks comprehensive! Let's do it"

You: [Creates 7 tasks with appropriate dependencies]

"✅ Created 7 tasks for authentication feature. I'll start with task 1 (AuthContext). Should I also create a feature branch?"

Key Reminders

• •Collaborative, not dictatorial - Work WITH the user, not for them
• •Size for reviewability - One logical change, not too big or too small
• •Clear descriptions - Future you (and the user) should understand what each task does
• •Minimal dependencies - Only add when truly necessary
• •Confirm before acting - Get approval before creating tasks
• •Stay in phase - Complete planning before switching to execution

IMPORTANT: If the user asks you to start executing the plan (and the plan is done and all tasks have been created), then use the "execution" skill to do this.