Planning: Скилл для создания технических планов

--- name: planning description: Implementation planning skill. Creates detailed technical plans through interactive research and iteration. --- # Planning You are creating detailed implementation plans through an interactive, iterative process. Be skeptical, thorough, and collaborative. ## Working Agreement These instructions establish a working agreement between you and the user. The key principles are: 1. **AskUserQuestion is your primary communication tool** - Whenever you need to ask the user anything (clarifications, design decisions, preferences, approvals), use the **AskUserQuestion tool**. Don't output questions as plain text - always use the structured tool so the user can respond efficiently. 2. **Establish preferences upfront** - Ask about user preferences at the start of the workflow, not at the end when they may want to move on. 3. **Autonomy mode guides interaction level** - The user's chosen autonomy level determines how often you check in, but AskUserQuestion remains the mechanism for all questions. ### User Preferences Before starting planning (unless autonomy is Autopilot), establish these preferences: **Commit After Each Phase** - Use **AskUserQuestion** with: | Question | Options | |----------|---------| | "Would you like me to create a commit after each phase once manual verification passes?" | 1. Yes, commit after each phase passes (Recommended), 2. No, I'll handle commits myself | Store this preference and act on it during implementation (see "Commit Integration" section). **File Review Preference** - Check if the `file-review` plugin is available (look for `file-review:file-review` in available commands). If file-review plugin is installed, use **AskUserQuestion** with: | Question | Options | |----------|---------| | "Would you like to use file-review for inline feedback on the plan when it's ready?" | 1. Yes, open file-review when plan is ready (Recommended), 2. No, just show me the plan | Store this preference and act on it after plan creation (see "Review Integration" section). ## When to Use This skill activates when: - User invokes `/create-plan` command - Another skill references `**REQUIRED SUB-SKILL:** Use desplega:planning` - User asks to plan an implementation or create a technical spec ## Autonomy Mode At the start of planning, adapt your interaction level based on the autonomy mode: | Mode | Behavior | |------|----------| | **Autopilot** | Research independently, create complete plan, present for final review only | | **Critical** (Default) | Get buy-in at major decision points, present design options for approval | | **Verbose** | Check in at each step, validate understanding, confirm before each phase | The autonomy mode is passed by the invoking command. If not specified, default to **Critical**. ## Process Steps ### Prior Learning Recall **OPTIONAL SUB-SKILL:** If `~/.agentic-learnings.json` exists, run `/learning recall <current topic>` to check for relevant prior learnings before proceeding. ### Step 1: Context Gathering & Initial Analysis 1. **Read all mentioned files immediately and FULLY:** - Research documents, related plans, JSON/data files - **IMPORTANT**: Use Read tool WITHOUT limit/offset parameters - **CRITICAL**: Read files yourself before spawning sub-tasks 2. **Spawn initial research tasks:** - Use **codebase-locator** agent to find all files related to the task - Use **codebase-analyzer** agent to understand current implementation - Use **thoughts-locator** agent to find existing thoughts documents - Use context7 MCP for library/framework insights 3. **Read all files identified by research tasks** 4. **Analyze and verify understanding:** - Identify discrepancies or misunderstandings - Note assumptions needing verification 5. **Present understanding and questions (if not Autopilot):** First, present your findings as text: ``` Based on the research of the codebase, I understand we need to [summary]. I've found that: - [Current implementation detail with file:line reference] - [Relevant pattern or constraint discovered] ``` Then, if there are questions that research couldn't answer, use **AskUserQuestion** with: | Question | Options | |----------|---------| | "[Specific technical question]" | Provide relevant options based on the choices available | | "[Design preference question]" | Provide relevant options based on the choices available | ### Step 2: Research & Discovery 1. **If the user corrects any misunderstanding:** - Spawn new research tasks to verify - Read specific files/directories mentioned 2. **Create a research todo list** using TodoWrite 3. **Spawn parallel sub-tasks:** - **codebase-locator** - Find specific files - **codebase-analyzer** - Understand implementation details - **codebase-pattern-finder** - Find similar features to model after 4. **Present findings and design options (if not Autopilot):** First, present findings as text: ``` **Current State:** - [Key discovery about existing code] ``` Then, use **AskUserQuestion** to present design options: | Question | Options | |----------|---------| | "Which approach aligns best with your vision?" | 1. [Option A] - [brief description], 2. [Option B] - [brief description] | Include pros/cons in the option descriptions to help the user decide. ### Step 3: Plan Structure Development 1. **Create initial plan outline (if not Autopilot):** Present the outline as text: ``` 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] ``` Then, use **AskUserQuestion** to get approval: | Question | Options | |----------|---------| | "Does this phasing make sense?" | 1. Yes, proceed with this structure, 2. No, let's discuss changes | 2. **Get feedback on structure** before writing details ### Step 4: Detailed Plan Writing Before proceeding, exit plan mode to write the plan file. Write the plan to `thoughts/<username|shared>/plans/YYYY-MM-DD-description.md`. **Path selection:** Use the user's name (e.g., `thoughts/taras/plans/`) if known from context. Fall back to `thoughts/shared/plans/` when unclear. **CRITICAL**: Every phase MUST include a `### Success Criteria:` section with both `#### Automated Verification:` and `#### Manual Verification:` subsections. See "Success Criteria Requirements" section at the end of this document for the exact format. **QA Specs (optional)**: Phases that change user-facing behavior, add UI, modify API responses, or alter auth/permissions SHOULD include an optional `### QA Spec (optional):` section after the Success Criteria. See the template for the exact format. Phases that are internal refactors, type changes, config updates, or dependency bumps should omit QA specs. QA specs can live either inline in plan phases (for per-phase validation) or as a separate standalone document (for cross-cutting or feature-level QA). The inline approach is the default for plans; the QA skill handles both sources transparently. **Template:** Read and follow the template at `cc-plugin/base/skills/planning/template.md` The template includes: - Standard plan sections (Overview, Current State, Desired End State, etc.) - Multiple phase examples with proper Success Criteria structure - Correct heading hierarchy throughout ### Step 5: Review and Iterate 1. **Present draft plan location:** ``` I've created the implementation plan at: `thoughts/<username|shared>/plans/YYYY-MM-DD-description.md` Please review it. ``` 2. **Iterate based on feedback** (if not Autopilot) 3. **Offer structured review:** - After iteration, offer: "Would you like me to run `/review` on this plan for completeness and gap analysis?" - If yes, invoke the `desplega:reviewing` skill on the plan document 4. **Finalize the plan** - DO NOT START implementation 5. **Learning Capture:** **OPTIONAL SUB-SKILL:** If significant insights, patterns, gotchas, or decisions emerged during this workflow, consider using `desplega:learning` to capture them via `/learning capture`. Focus on learnings that would help someone else in a future session. 6. **Workflow handoff:** After the plan is finalized (and optionally reviewed), use **AskUserQuestion** with: | Question | Options | |----------|---------| | "The plan is ready. What's the next step?" | 1. Implement this plan (→ `/implement-plan`), 2. Run a review first (→ `/review`), 3. Done for now (park the plan) | Based on the answer: - **Implement**: Suggest the `/implement-plan` command with the plan file path - **Review**: Invoke the `desplega:reviewing` skill on the plan document - **Done**: Set the plan's `status` to `ready` or `parked` as appropriate ## Review Integration If the `file-review` plugin is available and the user selected "Yes" during User Preferences setup: - After creating plans, invoke `/file-review:file-review <path>` - If user selected "No" or autonomy mode is Autopilot, skip this step ## Commit Integration If the user selected "Yes" to commits during User Preferences setup: - After each phase's manual verification passes, create a commit with a descriptive message - Commit message format: `[phase N] <brief description of what the phase accomplished>` - Only commit after explicit confirmation that manual verification passed - If user selected "No", skip commits entirely - the user will handle them ## Important Guidelines 1. **Be Skeptical**: Question vague requirements, verify with code 2. **Be Interactive**: Don't write full plan in one shot (unless Autopilot) 3. **Be Thorough**: Read context files COMPLETELY, include file:line references 4. **Be Practical**: Focus on incremental, testable changes 5. **No Open Questions**: Research or clarify immediately, don't leave questions in plan ## Success Criteria Requirements (MANDATORY) **Every phase MUST have a Success Criteria section.** Plans without proper success criteria are incomplete. ### Required Structure Each phase must end with this exact structure: ```markdown ### Success Criteria: #### Automated Verification: - [ ] [Command that can be run]: `command here` - [ ] [Another automated check]: `command here` #### Manual Verification: - [ ] [Human testing step] - [ ] [Another manual check] **Implementation Note**: [When to pause for confirmation] ``` ### Heading Hierarchy Use these exact heading levels (this is critical for consistency): - `### Success Criteria:` (h3) - section header - `#### Automated Verification:` (h4) - subsection - `#### Manual Verification:` (h4) - subsection ### What Goes Where | Type | Examples | |------|----------| | **Automated** | `make test`, `npm run lint`, `tsc --noEmit`, `ls path/to/file`, `grep pattern file` | | **Manual** | UI interactions, visual checks, performance testing, edge case validation | ### Validation Checklist Before finalizing any plan, verify: - [ ] Every phase has `### Success Criteria:` section - [ ] Each has `#### Automated Verification:` with runnable commands - [ ] Each has `#### Manual Verification:` with human testing steps - [ ] All items use checkbox format `- [ ]` - [ ] Automated checks are actual commands (not descriptions) - [ ] Phases with user-facing changes have optional `### QA Spec` sections (if applicable)