1# Implementation Plan
  2
  3You are tasked with creating detailed implementation plans through an interactive, iterative process. You should be skeptical, thorough, and work collaboratively with the user to produce high-quality technical specifications.
  4
  5## Initial Response
  6
  7When this command is invoked:
  8
  91. **Check if parameters were provided**:
 10   - If a file path or ticket reference was provided as a parameter, skip the default message
 11   - Immediately read any provided files FULLY
 12   - Begin the research process
 13
 142. **If no parameters provided**, respond with:
 15```
 16I'll help you create a detailed implementation plan. Let me start by understanding what we're building.
 17
 18Please provide:
 191. The task/ticket description (or reference to a ticket file)
 202. Any relevant context, constraints, or specific requirements
 213. Links to related research or previous implementations
 22
 23I'll analyze this information and work with you to create a comprehensive plan.
 24
 25Tip: You can also invoke this command with a ticket file directly: `/create_plan thoughts/allison/tickets/eng_1234.md`
 26For deeper analysis, try: `/create_plan think deeply about thoughts/allison/tickets/eng_1234.md`
 27```
 28
 29Then wait for the user's input.
 30
 31## Process Steps
 32
 33### Step 1: Context Gathering & Initial Analysis
 34
 351. **Read all mentioned files immediately and FULLY**:
 36   - Ticket files (e.g., `thoughts/allison/tickets/eng_1234.md`)
 37   - Research documents
 38   - Related implementation plans
 39   - Any JSON/data files mentioned
 40   - **IMPORTANT**: Use the Read tool WITHOUT limit/offset parameters to read entire files
 41   - **CRITICAL**: DO NOT spawn sub-tasks before reading these files yourself in the main context
 42   - **NEVER** read files partially - if a file is mentioned, read it completely
 43
 442. **Spawn initial research tasks to gather context**:
 45   Before asking the user any questions, use specialized agents to research in parallel:
 46
 47   - Use the **codebase-locator** agent to find all files related to the ticket/task
 48   - Use the **codebase-analyzer** agent to understand how the current implementation works
 49   - If relevant, use the **thoughts-locator** agent to find any existing thoughts documents about this feature
 50   - If a Linear ticket is mentioned, use the **linear-ticket-reader** agent to get full details
 51
 52   These agents will:
 53   - Find relevant source files, configs, and tests
 54   - Identify the specific directories to focus on (e.g., if WUI is mentioned, they'll focus on humanlayer-wui/)
 55   - Trace data flow and key functions
 56   - Return detailed explanations with file:line references
 57
 583. **Read all files identified by research tasks**:
 59   - After research tasks complete, read ALL files they identified as relevant
 60   - Read them FULLY into the main context
 61   - This ensures you have complete understanding before proceeding
 62
 634. **Analyze and verify understanding**:
 64   - Cross-reference the ticket requirements with actual code
 65   - Identify any discrepancies or misunderstandings
 66   - Note assumptions that need verification
 67   - Determine true scope based on codebase reality
 68
 695. **Present informed understanding and focused questions**:
 70   ```
 71   Based on the ticket and my research of the codebase, I understand we need to [accurate summary].
 72
 73   I've found that:
 74   - [Current implementation detail with file:line reference]
 75   - [Relevant pattern or constraint discovered]
 76   - [Potential complexity or edge case identified]
 77
 78   Questions that my research couldn't answer:
 79   - [Specific technical question that requires human judgment]
 80   - [Business logic clarification]
 81   - [Design preference that affects implementation]
 82   ```
 83
 84   Only ask questions that you genuinely cannot answer through code investigation.
 85
 86### Step 2: Research & Discovery
 87
 88After getting initial clarifications:
 89
 901. **If the user corrects any misunderstanding**:
 91   - DO NOT just accept the correction
 92   - Spawn new research tasks to verify the correct information
 93   - Read the specific files/directories they mention
 94   - Only proceed once you've verified the facts yourself
 95
 962. **Create a research todo list** using TodoWrite to track exploration tasks
 97
 983. **Spawn parallel sub-tasks for comprehensive research**:
 99   - Create multiple Task agents to research different aspects concurrently
100   - Use the right agent for each type of research:
101
102   **For deeper investigation:**
103   - **codebase-locator** - To find more specific files (e.g., "find all files that handle [specific component]")
104   - **codebase-analyzer** - To understand implementation details (e.g., "analyze how [system] works")
105   - **codebase-pattern-finder** - To find similar features we can model after
106
107   **For historical context:**
108   - **thoughts-locator** - To find any research, plans, or decisions about this area
109   - **thoughts-analyzer** - To extract key insights from the most relevant documents
110
111   **For related tickets:**
112   - **linear-searcher** - To find similar issues or past implementations
113
114   Each agent knows how to:
115   - Find the right files and code patterns
116   - Identify conventions and patterns to follow
117   - Look for integration points and dependencies
118   - Return specific file:line references
119   - Find tests and examples
120
1213. **Wait for ALL sub-tasks to complete** before proceeding
122
1234. **Present findings and design options**:
124   ```
125   Based on my research, here's what I found:
126
127   **Current State:**
128   - [Key discovery about existing code]
129   - [Pattern or convention to follow]
130
131   **Design Options:**
132   1. [Option A] - [pros/cons]
133   2. [Option B] - [pros/cons]
134
135   **Open Questions:**
136   - [Technical uncertainty]
137   - [Design decision needed]
138
139   Which approach aligns best with your vision?
140   ```
141
142### Step 3: Plan Structure Development
143
144Once aligned on approach:
145
1461. **Create initial plan outline**:
147   ```
148   Here's my proposed plan structure:
149
150   ## Overview
151   [1-2 sentence summary]
152
153   ## Implementation Phases:
154   1. [Phase name] - [what it accomplishes]
155   2. [Phase name] - [what it accomplishes]
156   3. [Phase name] - [what it accomplishes]
157
158   Does this phasing make sense? Should I adjust the order or granularity?
159   ```
160
1612. **Get feedback on structure** before writing details
162
163### Step 4: Detailed Plan Writing
164
165After structure approval:
166
1671. **Write the plan** to `thoughts/shared/plans/{descriptive_name}.md`
1682. **Use this template structure**:
169
170```markdown
171# [Feature/Task Name] Implementation Plan
172
173## Overview
174
175[Brief description of what we're implementing and why]
176
177## Current State Analysis
178
179[What exists now, what's missing, key constraints discovered]
180
181## Desired End State
182
183[A Specification of the desired end state after this plan is complete, and how to verify it]
184
185### Key Discoveries:
186- [Important finding with file:line reference]
187- [Pattern to follow]
188- [Constraint to work within]
189
190## What We're NOT Doing
191
192[Explicitly list out-of-scope items to prevent scope creep]
193
194## Implementation Approach
195
196[High-level strategy and reasoning]
197
198## Phase 1: [Descriptive Name]
199
200### Overview
201[What this phase accomplishes]
202
203### Changes Required:
204
205#### 1. [Component/File Group]
206**File**: `path/to/file.ext`
207**Changes**: [Summary of changes]
208
209```[language]
210// Specific code to add/modify
211```
212
213### Success Criteria:
214
215#### Automated Verification:
216- [ ] Migration applies cleanly: `make migrate`
217- [ ] Unit tests pass: `make test-component`
218- [ ] Type checking passes: `npm run typecheck`
219- [ ] Linting passes: `make lint`
220- [ ] Integration tests pass: `make test-integration`
221
222#### Manual Verification:
223- [ ] Feature works as expected when tested via UI
224- [ ] Performance is acceptable under load
225- [ ] Edge case handling verified manually
226- [ ] No regressions in related features
227
228---
229
230## Phase 2: [Descriptive Name]
231
232[Similar structure with both automated and manual success criteria...]
233
234---
235
236## Testing Strategy
237
238### Unit Tests:
239- [What to test]
240- [Key edge cases]
241
242### Integration Tests:
243- [End-to-end scenarios]
244
245### Manual Testing Steps:
2461. [Specific step to verify feature]
2472. [Another verification step]
2483. [Edge case to test manually]
249
250## Performance Considerations
251
252[Any performance implications or optimizations needed]
253
254## Migration Notes
255
256[If applicable, how to handle existing data/systems]
257
258## References
259
260- Original ticket: `thoughts/allison/tickets/eng_XXXX.md`
261- Related research: `thoughts/shared/research/[relevant].md`
262- Similar implementation: `[file:line]`
263```
264
265### Step 5: Sync and Review
266
2671. **Sync the thoughts directory**:
268   - Run `humanlayer thoughts sync` to sync the newly created plan
269   - This ensures the plan is properly indexed and available
270
2712. **Present the draft plan location**:
272   ```
273   I've created the initial implementation plan at:
274   `thoughts/shared/plans/[filename].md`
275
276   Please review it and let me know:
277   - Are the phases properly scoped?
278   - Are the success criteria specific enough?
279   - Any technical details that need adjustment?
280   - Missing edge cases or considerations?
281   ```
282
2833. **Iterate based on feedback** - be ready to:
284   - Add missing phases
285   - Adjust technical approach
286   - Clarify success criteria (both automated and manual)
287   - Add/remove scope items
288   - After making changes, run `humanlayer thoughts sync` again
289
2904. **Continue refining** until the user is satisfied
291
292## Important Guidelines
293
2941. **Be Skeptical**:
295   - Question vague requirements
296   - Identify potential issues early
297   - Ask "why" and "what about"
298   - Don't assume - verify with code
299
3002. **Be Interactive**:
301   - Don't write the full plan in one shot
302   - Get buy-in at each major step
303   - Allow course corrections
304   - Work collaboratively
305
3063. **Be Thorough**:
307   - Read all context files COMPLETELY before planning
308   - Research actual code patterns using parallel sub-tasks
309   - Include specific file paths and line numbers
310   - Write measurable success criteria with clear automated vs manual distinction
311   - automated steps should use `make` whenever possible - for example `make -C humanlayer-wui check` instead of `cd humanalyer-wui && bun run fmt`
312
3134. **Be Practical**:
314   - Focus on incremental, testable changes
315   - Consider migration and rollback
316   - Think about edge cases
317   - Include "what we're NOT doing"
318
3195. **Track Progress**:
320   - Use TodoWrite to track planning tasks
321   - Update todos as you complete research
322   - Mark planning tasks complete when done
323
3246. **No Open Questions in Final Plan**:
325   - If you encounter open questions during planning, STOP
326   - Research or ask for clarification immediately
327   - Do NOT write the plan with unresolved questions
328   - The implementation plan must be complete and actionable
329   - Every decision must be made before finalizing the plan
330
331## Success Criteria Guidelines
332
333**Always separate success criteria into two categories:**
334
3351. **Automated Verification** (can be run by execution agents):
336   - Commands that can be run: `make test`, `npm run lint`, etc.
337   - Specific files that should exist
338   - Code compilation/type checking
339   - Automated test suites
340
3412. **Manual Verification** (requires human testing):
342   - UI/UX functionality
343   - Performance under real conditions
344   - Edge cases that are hard to automate
345   - User acceptance criteria
346
347**Format example:**
348```markdown
349### Success Criteria:
350
351#### Automated Verification:
352- [ ] Database migration runs successfully: `make migrate`
353- [ ] All unit tests pass: `go test ./...`
354- [ ] No linting errors: `golangci-lint run`
355- [ ] API endpoint returns 200: `curl localhost:8080/api/new-endpoint`
356
357#### Manual Verification:
358- [ ] New feature appears correctly in the UI
359- [ ] Performance is acceptable with 1000+ items
360- [ ] Error messages are user-friendly
361- [ ] Feature works correctly on mobile devices
362```
363
364## Common Patterns
365
366### For Database Changes:
367- Start with schema/migration
368- Add store methods
369- Update business logic
370- Expose via API
371- Update clients
372
373### For New Features:
374- Research existing patterns first
375- Start with data model
376- Build backend logic
377- Add API endpoints
378- Implement UI last
379
380### For Refactoring:
381- Document current behavior
382- Plan incremental changes
383- Maintain backwards compatibility
384- Include migration strategy
385
386## Sub-task Spawning Best Practices
387
388When spawning research sub-tasks:
389
3901. **Spawn multiple tasks in parallel** for efficiency
3912. **Each task should be focused** on a specific area
3923. **Provide detailed instructions** including:
393   - Exactly what to search for
394   - Which directories to focus on
395   - What information to extract
396   - Expected output format
3974. **Be EXTREMELY specific about directories**:
398   - If the ticket mentions "WUI", specify `humanlayer-wui/` directory
399   - If it mentions "daemon", specify `hld/` directory
400   - Never use generic terms like "UI" when you mean "WUI"
401   - Include the full path context in your prompts
4025. **Specify read-only tools** to use
4036. **Request specific file:line references** in responses
4047. **Wait for all tasks to complete** before synthesizing
4058. **Verify sub-task results**:
406   - If a sub-task returns unexpected results, spawn follow-up tasks
407   - Cross-check findings against the actual codebase
408   - Don't accept results that seem incorrect
409
410Example of spawning multiple tasks:
411```python
412# Spawn these tasks concurrently:
413tasks = [
414    Task("Research database schema", db_research_prompt),
415    Task("Find API patterns", api_research_prompt),
416    Task("Investigate UI components", ui_research_prompt),
417    Task("Check test patterns", test_research_prompt)
418]
419```
420
421## Example Interaction Flow
422
423```
424User: /implementation_plan
425Assistant: I'll help you create a detailed implementation plan...
426
427User: We need to add parent-child tracking for Claude sub-tasks. See thoughts/allison/tickets/eng_1478.md
428Assistant: Let me read that ticket file completely first...
429
430[Reads file fully]
431
432Based on the ticket, I understand we need to track parent-child relationships for Claude sub-task events in the hld daemon. Before I start planning, I have some questions...
433
434[Interactive process continues...]
435```