From 0a9dd18a64a7ead12ccb431fa23773598a8fa9fe Mon Sep 17 00:00:00 2001 From: Daniel Bauer Date: Fri, 2 Jan 2026 09:54:09 +0100 Subject: [PATCH] add claude commands --- dot_claude/commands/implement_plan.md | 84 +++++ dot_claude/commands/literal_create_plan.md | 361 +++++++++++++++++++++ dot_claude/commands/research_codebase.md | 139 ++++++++ 3 files changed, 584 insertions(+) create mode 100644 dot_claude/commands/implement_plan.md create mode 100644 dot_claude/commands/literal_create_plan.md create mode 100644 dot_claude/commands/research_codebase.md diff --git a/dot_claude/commands/implement_plan.md b/dot_claude/commands/implement_plan.md new file mode 100644 index 0000000..94eabf2 --- /dev/null +++ b/dot_claude/commands/implement_plan.md @@ -0,0 +1,84 @@ +--- +description: Implement from spec with verification +--- + +# Implement Plan + +You are tasked with implementing a technical spec/plan. These plans contain phases with specific changes and success criteria. + +## Getting Started + +When given a spec path: +- Read the spec completely and check for any existing checkmarks (- [x]) +- Read the original ticket or other related documentation if provided and all files mentioned in the plan +- **Read files fully** - never use limit/offset parameters, you need complete context +- Think deeply about how the pieces fit together +- Create a todo list to track your progress +- Start implementing if you understand what needs to be done + +If no plan path provided, ask for one. + +## Implementation Philosophy + +Plans are carefully designed, but reality can be messy. Your job is to: +- Follow the plan's intent while adapting to what you find +- Implement each phase fully before moving to the next +- Verify your work makes sense in the broader codebase context +- Update checkboxes in the plan as you complete sections + +When things don't match the plan exactly, think about why and communicate clearly. The plan is your guide, but your judgment matters too. + +If you encounter a mismatch: +- STOP and think deeply about why the plan can't be followed +- Present the issue clearly: + ``` + Issue in Phase [N]: + Expected: [what the plan says] + Found: [actual situation] + Why this matters: [explanation] + + How should I proceed? + ``` + +## Verification Approach + +After implementing a phase: +- Run the success criteria checks +- Fix any issues before proceeding +- Update your progress in both the plan and your todos +- Check off completed items in the plan file itself using Edit +- **Pause for human verification**: After completing all automated verification for a phase, pause and inform the human that the phase is ready for manual testing. Use this format: + ``` + Phase [N] Complete - Ready for Manual Verification + + Automated verification passed: + - [List automated checks that passed] + + Please perform the manual verification steps listed in the plan: + - [List manual verification items from the plan] + + Let me know when manual testing is complete so I can proceed to Phase [N+1]. + ``` + +If instructed to execute multiple phases consecutively, skip the pause until the last phase. Otherwise, assume you are just doing one phase. + +Do not check off items in the manual testing steps until confirmed by the user. + + +## If You Get Stuck + +When something isn't working as expected: +- First, make sure you've read and understood all the relevant code +- Consider if the codebase has evolved since the plan was written +- Present the mismatch clearly and ask for guidance + +Use sub-tasks sparingly - mainly for targeted debugging or exploring unfamiliar territory. + +## Resuming Work + +If the plan has existing checkmarks: +- Trust that completed work is done +- Pick up from the first unchecked item +- Verify previous work only if something seems off + +Remember: You're implementing a solution, not just checking boxes. Keep the end goal in mind and maintain forward momentum. diff --git a/dot_claude/commands/literal_create_plan.md b/dot_claude/commands/literal_create_plan.md new file mode 100644 index 0000000..7ce23d4 --- /dev/null +++ b/dot_claude/commands/literal_create_plan.md @@ -0,0 +1,361 @@ +--- +description: Create detailed implementation plans through interactive research and iteration +model: opus +--- + +# Implementation Plan + +You 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. + +## Process Steps + +### Step 1: Context Gathering & Initial Analysis + +1. **Read all mentioned files immediately and FULLY**: + - Ticket files and links to issues + - Research documents + - Related implementation plans + - Any JSON/data files mentioned + - **IMPORTANT**: Use the Read tool WITHOUT limit/offset parameters to read entire files + - **CRITICAL**: DO NOT spawn sub-tasks before reading these files yourself in the main context + - **NEVER** read files partially - if a file is mentioned, read it completely + +2. **Spawn initial research tasks to gather context**: + Before asking the user any questions, use agents to research in parallel. These agents should be tasked to: + - Find relevant source files, configs, and tests + - Identify the specific directories to focus on + - Trace data flow and key functions + - Return detailed explanations with file:line references + +3. **Read all files identified by research tasks**: + - After research tasks complete, read ALL files they identified as relevant + - Read them FULLY into the main context + - This ensures you have complete understanding before proceeding + +4. **Analyze and verify understanding**: + - Cross-reference the requirements with actual code + - Identify any discrepancies or misunderstandings + - Note assumptions that need verification + - Determine true scope based on codebase reality + +5. **Present informed understanding and focused questions**: + ``` + Based on the task and my research of the codebase, I understand we need to [accurate summary]. + + I've found that: + - [Current implementation detail with file:line reference] + - [Relevant pattern or constraint discovered] + - [Potential complexity or edge case identified] + + Questions that my research couldn't answer: + - [Specific technical question that requires human judgment] + - [Business logic clarification] + - [Design preference that affects implementation] + ``` + + Only ask questions that you genuinely cannot answer through code investigation. + +### Step 2: Research & Discovery + +After getting initial clarifications: + +1. **If the user corrects any misunderstanding**: + - DO NOT just accept the correction + - Spawn new research tasks to verify the correct information + - Read the specific files/directories they mention + - Only proceed once you've verified the facts yourself + +2. **Create a research todo list** using TodoWrite to track exploration tasks + +3. **Spawn parallel sub-tasks for comprehensive research**: + - Create multiple agents to research different aspects concurrently: + - Find related documentation + - Find more specific files (e.g., "find all files that handle [specific component]") + - Understand implementation details (e.g., "analyze how [system] works") + - Find patterns, best practices and similar features we can model after + + The key is to use each agent intelligently to: + - Find the right files and code patterns + - Identify conventions and patterns to follow + - Look for integration points and dependencies + - Return specific file:line references + - Find tests and examples + +3. **Wait for ALL sub-tasks to complete** before proceeding + +4. **Present findings and design options**: + - Provide current state + - Provide different design options with pros/cons + - Recommend one of the design options + +### Step 3: Plan Structure Development + +Once aligned on an approach with the user: + +1. **Create initial plan outline**: + ``` + Here's my proposed plan structure: + + ## Overview + [1-2 sentence summary] + + ## Implementation Phases: + 1. [Phase name] - [what it accomplishes] + 2. [Phase name] - [what it accomplishes] + 3. [Phase name] - [what it accomplishes] + + Does this phasing make sense? Should I adjust the order or granularity? + ``` + +2. **Get feedback on structure** before writing details + +### Step 4: Detailed Plan Writing + +After structure approval, write a detailed plan as markdown file. Use this template: + +````markdown +# [Feature/Task Name] Implementation Plan + +## Overview + +[Brief description of what we're implementing and why] + +## Current State Analysis + +[What exists now, what's missing, key constraints discovered] + +## Desired End State + +[A Specification of the desired end state after this plan is complete, and how to verify it] + +### Key Discoveries: +- [Important finding with file:line reference] +- [Pattern to follow] +- [Constraint to work within] + +## What We're NOT Doing + +[Explicitly list out-of-scope items to prevent scope creep] + +## Implementation Approach + +[High-level strategy and reasoning] + +## Phase 1: [Descriptive Name] + +### Overview +[What this phase accomplishes] + +### Changes Required: + +#### 1. [Component/File Group] +**File**: `path/to/file.ext` +**Changes**: [Summary of changes] + +```[language] +// Specific code to add/modify +``` + +### Success Criteria: +[How to verify success manually and via tests as checklist] + +**Implementation Note**: After completing this phase and all automated verification passes, pause here for manual confirmation from the human that the manual testing was successful before proceeding to the next phase. + +--- + +## Phase 2: [Descriptive Name] + +[Similar structure with both automated and manual success criteria...] + +--- + +## Testing Strategy + +### Unit Tests: +- [What to test] +- [Key edge cases] + +### Integration Tests: +- [End-to-end scenarios] + +### Manual Testing Steps: +1. [Specific step to verify feature] +2. [Another verification step] +3. [Edge case to test manually] + +## Performance Considerations + +[Any performance implications or optimizations needed] + +## Migration Notes + +[If applicable, how to handle existing data/systems] + +## References + +- Original ticket: `thoughts/allison/tickets/eng_XXXX.md` +- Related research: `thoughts/shared/research/[relevant].md` +- Similar implementation: `[file:line]` +```` + +### Step 5: Sync and Review + +1. **Present the draft plan location**: + ``` + I've created the initial implementation plan at: + `thoughts/shared/plans/YYYY-MM-DD-ENG-XXXX-description.md` + + Please review it and let me know: + - Are the phases properly scoped? + - Are the success criteria specific enough? + - Any technical details that need adjustment? + - Missing edge cases or considerations? + ``` + +2. **Iterate based on feedback** - be ready to: + - Add missing phases + - Adjust technical approach + - Clarify success criteria (both automated and manual) + - Add/remove scope items + +3. **Continue refining** until the user is satisfied + +## Important Guidelines + +1. **Be Skeptical**: + - Question vague requirements + - Identify potential issues early + - Ask "why" and "what about" + - Don't assume - verify with code + +2. **Be Interactive**: + - Don't write the full plan in one shot + - Get buy-in at each major step + - Allow course corrections + - Work collaboratively + +3. **Be Thorough**: + - Read all context files COMPLETELY before planning + - Research actual code patterns using parallel sub-tasks + - Include specific file paths and line numbers + - Write measurable success criteria with clear automated vs manual distinction + +4. **Be Practical**: + - Focus on incremental, testable changes + - Consider migration and rollback + - Think about edge cases + - Include "what we're NOT doing" + +5. **Track Progress**: + - Use TodoWrite to track planning tasks + - Update todos as you complete research + - Mark planning tasks complete when done + +6. **No Open Questions in Final Plan**: + - If you encounter open questions during planning, STOP + - Research or ask for clarification immediately + - Do NOT write the plan with unresolved questions + - The implementation plan must be complete and actionable + - Every decision must be made before finalizing the plan + +## Success Criteria Guidelines + +**Always separate success criteria into two categories:** + +1. **Automated Verification** (can be run by execution agents): + - Commands that can be run: `make test`, `npm run lint`, etc. + - Specific files that should exist + - Code compilation/type checking + - Automated test suites + +2. **Manual Verification** (requires human testing): + - UI/UX functionality + - Performance under real conditions + - Edge cases that are hard to automate + - User acceptance criteria + +**Format example:** +```markdown +### Success Criteria: + +#### Automated Verification: +- [ ] Database migration runs successfully: `make migrate` +- [ ] All unit tests pass: `go test ./...` +- [ ] No linting errors: `ansible-lint` +- [ ] API endpoint returns 200: `curl localhost:8080/api/new-endpoint` + +#### Manual Verification: +- [ ] New feature appears correctly in the UI +- [ ] Performance is acceptable with 1000+ items +- [ ] Error messages are user-friendly +- [ ] Feature works correctly on mobile devices +``` + +## Common Patterns + +### For Database Changes: +- Start with schema/migration +- Add store methods +- Update business logic +- Expose via API +- Update clients + +### For New Features: +- Research existing patterns first +- Start with data model +- Build backend logic +- Add API endpoints +- Implement UI last + +### For Refactoring: +- Document current behavior +- Plan incremental changes +- Maintain backwards compatibility if possible +- Include migration strategy + +## Sub-task Spawning Best Practices + +When spawning research sub-tasks: + +1. **Spawn multiple tasks in parallel** for efficiency +2. **Each task should be focused** on a specific area +3. **Provide detailed instructions** including: + - Exactly what to search for + - Which directories to focus on + - What information to extract + - Expected output format +4. **Specify read-only tools** to use +5. **Request specific file:line references** in responses +6. **Wait for all tasks to complete** before synthesizing +7. **Verify sub-task results**: + - If a sub-task returns unexpected results, spawn follow-up tasks + - Cross-check findings against the actual codebase + - Don't accept results that seem incorrect + +Example of spawning multiple tasks: +```python +# Spawn these tasks concurrently: +tasks = [ + Task("Research database schema", db_research_prompt), + Task("Find API patterns", api_research_prompt), + Task("Investigate UI components", ui_research_prompt), + Task("Check test patterns", test_research_prompt) +] +``` + +## Example Interaction Flow + +``` +User: /create_plan +Assistant: I'll help you create a detailed implementation plan... + +User: We need to add parent-child tracking for Claude sub-tasks. See /path/to/spec.md +Assistant: Let me read that ticket file completely first... + +[Reads file fully] + +Based 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... + +[Interactive process continues...] +``` diff --git a/dot_claude/commands/research_codebase.md b/dot_claude/commands/research_codebase.md new file mode 100644 index 0000000..1183dd8 --- /dev/null +++ b/dot_claude/commands/research_codebase.md @@ -0,0 +1,139 @@ +--- +description: Document codebase as-is +model: opus +--- + +# Research Codebase + +You are tasked with conducting comprehensive research across the codebase +to answer user questions by spawning parallel sub-agents and synthesizing their findings. + +## CRITICAL: YOUR ONLY JOB IS TO DOCUMENT AND EXPLAIN THE CODEBASE AS IT EXISTS TODAY + +- DO NOT suggest improvements or changes unless the user explicitly asks for them +- DO NOT perform root cause analysis unless the user explicitly asks for them +- DO NOT propose future enhancements unless the user explicitly asks for them +- DO NOT critique the implementation or identify problems +- DO NOT recommend refactoring, optimization, or architectural changes +- ONLY describe what exists, where it exists, how it works, and how components interact +- You are creating a technical map/documentation of the existing system + +## Steps to follow after receiving the research query + +1. **Read any directly mentioned files first:** + - If the user mentions specific files (tickets, docs, JSON), read them FULLY first + - **IMPORTANT**: Use the Read tool WITHOUT limit/offset parameters to read entire files + - **CRITICAL**: Read these files yourself in the main context before spawning any sub-tasks + - This ensures you have full context before decomposing the research + +2. **Analyze and decompose the research question:** + - Break down the user's query into composable research areas + - Take time to ultrathink about the underlying patterns, connections, and architectural implications the user might be seeking + - Identify specific components, patterns, or concepts to investigate + - Create a research plan using TodoWrite to track all subtasks + - Consider which directories, files, or architectural patterns are relevant + +3. **Spawn parallel sub-agent tasks for comprehensive research:** + - Create multiple agents to research different aspects concurrently: + - Use an agent to locate WHERE files and components live + - Use an agent analyze and understand HOW specific code works (without critiquing it) + - Use an agent to find examples of existing patterns (without evaluating them) + - Use an agent for web research for external documentation and resources, but only if the user epplicitly asks for this. IF you use web-research agents, instruct them to return LINKS with their findings, and please INCLUDE those links in your final report + + The key is to use these agents intelligently: + - Start with locator agents to find what exists + - Then use analyzer agents on the most promising findings to document how they work + - Run multiple agents in parallel when they're searching for different things + - Remind agents they are documenting, not evaluating or improving + +4. **Wait for all sub-agents to complete and synthesize findings:** + - IMPORTANT: Wait for ALL sub-agent tasks to complete before proceeding + - Compile all sub-agent results (both codebase and thoughts findings) + - Prioritize live codebase findings as primary source of truth + - Use thoughts and findings as supplementary historical context + - Connect findings across different components + - Include specific file paths and line numbers for reference + - Verify all thoughts/ paths are correct (e.g., thoughts/allison/ not thoughts/shared/ for personal files) + - Highlight patterns, connections, and architectural decisions + - Answer the user's specific questions with concrete evidence + +5. **Generate research document:** + - Create a structured research document with your findings as markdown file. + - Structure the document with YAML frontmatter followed by content: + ```markdown + --- + repository: [Repository name] + branch: [Current branch name] + git_commit: [Current commit hash] + topic: "[User's Question/Topic]" + last_updated: [Current date in YYYY-MM-DD format] + --- + + # [User's Question/Topic] + + ## Research Question + [Original user query] + + ## Summary + [High-level documentation of what was found, answering the user's question by describing what exists] + + ## Detailed Findings + + ### [Component/Area 1] + - Description of what exists ([file.ext:line](link)) + - How it connects to other components + - Current implementation details (without evaluation) + + ### [Component/Area 2] + ... + + ## Code References + - `path/to/file.py:123` - Description of what's there + - `another/file.ts:45-67` - Description of the code block + + ## Architecture Documentation + [Current patterns, conventions, and design implementations found in the codebase] + + ## Historical Context (from thoughts/) + [Relevant insights from thoughts/ directory with references] + - `thoughts/shared/something.md` - Historical decision about X + - `thoughts/local/notes.md` - Past exploration of Y + Note: Paths exclude "searchable/" even if found there + + ## Related Research + [Links to other research documents in thoughts/shared/research/] + + ## Open Questions + [Any areas that need further investigation] + ``` + +6. **Present findings:** + - Present a concise summary of findings to the user + - Include key file references for easy navigation + - Ask if they have follow-up questions or need clarification + +7. **Handle follow-up questions:** + - If the user has follow-up questions, append to the same research document + - Spawn new sub-agents as needed for additional investigation + - Continue updating the document until no more follow up questions are asked + +## Important notes: +- Always use parallel Task agents to maximize efficiency and minimize context usage +- Always validate exsisting research documents during research. Don't rely on old documents +- Old research documents provide historical context to supplement live findings. +- Focus on finding concrete file paths and line numbers for developer reference +- Research documents should be self-contained with all necessary context +- Each sub-agent prompt should be specific and focused on read-only documentation operations +- Document cross-component connections and how systems interact +- Keep the main agent focused on synthesis, not deep file reading +- Have sub-agents document examples and usage patterns as they exist +- Explore all existing research documents and documentation. +- **CRITICAL**: You and all sub-agents are documentarians, not evaluators +- **REMEMBER**: Document what IS, not what SHOULD BE +- **NO RECOMMENDATIONS**: Only describe the current state of the codebase +- **File reading**: Always read mentioned files FULLY (no limit/offset) before spawning sub-tasks +- **Critical ordering**: Follow the numbered steps exactly + - ALWAYS read mentioned files first before spawning sub-tasks (step 1) + - ALWAYS wait for all sub-agents to complete before synthesizing (step 4) + - ALWAYS gather metadata before writing the document (step 5 before step 6) + - NEVER write the research document with placeholder values