# Plan Analysis > [Planning] Use when the user provides an implementation plan file and asks to analyze it, assess impact, update specifications, or verify planned changes. - Skill: `duc01226/plan-analysis-3` (Agent Skill) - Install (CLI): `npx skillmds@latest add duc01226/plan-analysis-3` - Raw SKILL.md: https://api.skillmd.com/api/skills/duc01226/plan-analysis-3/raw - Safety review: pending (external: skill-scanner PASS, skillspector CAUTION) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: duc01226 (https://skillmd.com/u/duc01226) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/duc01226/plan-analysis-3 --- ## Quick Summary **Goal:** Analyze an implementation plan, assess its impact on the codebase, and update specification documents accordingly. **Workflow:** 1. **Discovery** — Parse plan, extract requirements, catalog planned changes 2. **Knowledge Graph** — Build detailed component-level impact map with test/spec mappings 3. **Analysis** — Assess architecture impact, business logic changes, testing strategy 4. **Approval Gate** — Present findings for explicit user approval before any spec updates 5. **Spec Update** — Execute approved changes to specification documents **Key Rules:** - Planning-only skill -- never implement code changes - Always collaborate and get user approval before proceeding - Maintain bidirectional traceability between plan and specification **Be skeptical. Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence percentages (Idea should be more than 80%).** # Implementation Plan Analysis & Specification Update ## PLANNING-ONLY — Collaboration Required > **DO NOT** use the `EnterPlanMode` tool — you are ALREADY in a planning workflow. > **DO NOT** implement or execute any code changes. > **COLLABORATE** with the user: ask decision questions, present options with recommendations. > After plan analysis, validate findings with user approval. > **ASK** user to confirm the analysis before any next steps. You are to operate as an expert full-stack principal developer, software architect, and technical analyst to analyze a detailed implementation plan, perform comprehensive impact analysis, and update specification documents using the configured repository stack. **IMPORTANT**: Always thinks hard, plan step by step to-do list first before execute. Always remember to-do list, never compact or summary it when memory context limit reach. Always preserve and carry your to-do list through every operation. **Prerequisites:** --- ## PHASE 1: EXTERNAL MEMORY-DRIVEN IMPLEMENTATION PLAN ANALYSIS Build a structured knowledge model in `.ai/workspace/analysis/[plan-name].analysis.md`. ### PHASE 1A: INITIALIZATION AND DISCOVERY 1. **Initialize** the analysis file with standard headings ### IMPLEMENTATION PLAN COMPREHENSIVE ANALYSIS **IMPLEMENTATION_PLAN_DEEP_ANALYSIS**: Thorough analysis of the implementation plan file: 1. **Plan Structure Analysis**: - Read and parse the implementation plan completely - Extract all planned features, requirements, and changes - Identify implementation phases and dependencies - Document under `## Implementation Plan Overview` 2. **Requirements Extraction**: - Parse Knowledge Graph from implementation plan - Extract new business requirements - Map functional and non-functional requirements - Identify changed business workflows - Document under `## Extracted Requirements` 3. **Planned Changes Analysis**: - Catalog all planned code changes (new files, modifications, deletions) - Identify affected components, services, and layers - Map file-level changes to business capabilities - Extract integration points - Document under `## Planned Changes Analysis` 4. **Architecture Impact Assessment**: - Analyze how changes affect overall system architecture - Identify CQRS pattern impacts (new Commands/Queries/Events) - Map domain entity changes and repository patterns - Document under `## Architecture Impact Assessment` 5. **Existing Specification Analysis**: - Read and analyze existing specification document structure - Identify current test cases, requirements, entity relationships - Map existing test coverage to planned changes - Document under `## Current Specification Analysis` **AFFECTED_COMPONENTS_DISCOVERY**: For each planned change, discover: - Direct Dependencies - Indirect Dependencies - Test Coverage Impact - API Integration Impact - Cross-Service Communication - Database Schema Impact Save to `## Comprehensive File List` with: - `filePath`, `changeType`, `relationshipType`, `impactLevel` - `serviceContext`, `planContext`, `specificationRelevance` ### PHASE 1B: KNOWLEDGE GRAPH CONSTRUCTION **IMPORTANT: MUST ATTENTION DO WITH TODO LIST** For each file, document in `## Knowledge Graph`: - Standard fields plus plan-specific: - `currentContent`: Existing functionality (if file exists) - `plannedChanges`: Specific changes planned - `changeImpactAnalysis`: How changes affect other components - `testingRequirements`: New test cases needed - `specificationMapping`: How component maps to spec sections - `testCaseImpact`: Existing test cases needing modification ### PHASE 1C: SPECIFICATION MAPPING ANALYSIS - **Test Case Mapping**: Which existing test cases are affected - **Business Requirement Mapping**: How new requirements relate to existing - **Entity Relationship Impact**: Changes to entity relationships - **Workflow Integration**: How new workflows integrate with existing - **Coverage Gap Analysis**: Areas where new test cases needed ### PHASE 1D: OVERALL ANALYSIS Write comprehensive summary showing: - Complete end-to-end workflows affected - Architectural patterns impacted - Business logic workflow changes - Integration points affected - Comprehensive test coverage requirements --- ## PHASE 2: COMPREHENSIVE ANALYSIS AND PLANNING Generate detailed analysis under these headings: 1. **Implementation Impact Analysis**: Component impact, integration points, data flow changes, architectural-pattern compliance 2. **Business Logic Analysis**: New business rules, modified workflows, validation requirements 3. **Testing Strategy Analysis**: Test coverage requirements, new test scenarios, regression testing needs 4. **Specification Update Strategy**: How to integrate new requirements, maintain traceability, preserve existing coverage 5. **Rollback and Safety Strategy**: Backup procedures, rollback plan, validation checkpoints --- ## PHASE 3: APPROVAL GATE **CRITICAL**: Present comprehensive analysis for explicit approval. **DO NOT** proceed without it. --- ## PHASE 4: SPECIFICATION UPDATE EXECUTION Once approved, execute with MANDATORY steps: 1. **Backup Original Specification** 2. **Read and Parse Existing Specification** 3. **Execute Planned Updates**: - New Requirements Integration - Entity Relationship Updates - Test Case Enhancement - Traceability Matrix Updates - Coverage Analysis Updates 4. **Maintain Specification Structure** 5. **Quality Assurance Validation** --- ## SUCCESS VALIDATION Verify under `## Specification Validation`: - **Requirements Traceability**: All plan requirements mapped - **Test Coverage Validation**: All changes covered by tests - **Business Workflow Validation**: End-to-end workflows documented - **Integration Testing Coverage**: Cross-service impacts covered - **Regression Prevention**: Existing functionality protected --- ## Plan Analysis Guidelines - **Plan-Driven Analysis**: Base all analysis on the detailed implementation plan - **Specification Structure Preservation**: Maintain standardized specification format - **Comprehensive Impact Assessment**: Analyze direct and indirect effects - **End-to-End Workflow Mapping**: Understand affected business processes - **Enterprise Architecture Awareness**: Respect the project's architectural patterns - **Quality-Focused Testing**: Create comprehensive test specifications - **Specification Completeness**: Ensure full traceability - **Risk Assessment and Mitigation**: Identify risks and provide rollback strategies - **Bidirectional Traceability**: Maintain clear mapping between plan and spec - **Coverage Preservation**: Maintain existing test coverage while adding new ## Related - `plan` - `workflow-feature` - **MANDATORY FINAL TASKS:** After creating all planning todo tasks, ALWAYS add these three final tasks: 1. **Task: "Write test specifications for each phase"** — Add `## Test Specifications` with TC-{FEATURE}-{NNN} IDs to every phase file. Use `/spec [mode=tests]` if feature docs exist. Use `Evidence: TBD` for TDD-first mode. 2. **Task: "Run /plan-validate"** — Trigger `/plan-validate` skill to interview the user with critical questions and validate plan assumptions 3. **Task: "Run /plan-review"** — Trigger `/plan-review` skill to auto-review plan for validity, correctness, and best practices ## REMINDER — Planning-Only Skill > **DO NOT** use `EnterPlanMode` tool. > **DO NOT** start implementing. > **ALWAYS** validate with user approval after analysis. > **ASK** user to confirm findings before any execution begins. > **ASK** user for clarification when multiple approaches exist. --- > **[IMPORTANT]** Use `TaskCreate` to break ALL work into small tasks BEFORE starting — including tasks for each file read. This prevents context loss from long files. For simple tasks, AI MUST ATTENTION ask user whether to skip. **Prerequisites:** - `docs/specs/` — Test specifications by module (read existing TCs to include test strategy in plan) > **AI Mistake Prevention** — Failure modes to avoid on every task: > > **Re-read files after context changes.** Context compaction, resume, or long-running work can make memory stale; verify current files before acting. > **Verify generated content against source evidence.** AI hallucinates APIs, names, claims, and document facts. Check the relevant source before documenting or referencing. > **Check downstream references before deleting or renaming.** Removing an artifact can stale docs, generated mirrors, configs, and callers; map references first. > **Trace the full impact chain after edits.** Changing a definition can miss derived outputs and consumers. Follow the affected chain before declaring done. > **Verify ALL affected outputs, not just the first.** One green check is not all green checks; validate every output surface the change can affect. > **Assume existing values are intentional — ask WHY before changing OR flagging one as a defect.** Before changing or reporting a constant, limit, flag, cutoff, wording, or pattern, read nearby context and history, the CALLER's ordering, and 2+ sibling call sites of the same convention. A doc stating WHAT without WHY is missing rationale, not proof of a missing guard. > **Surface ambiguity before acting — don't pick silently.** Multiple valid interpretations require an explicit question or stated assumption with risk. > **Assert the outcome your system owns, not the intermediate state your infrastructure owns.** When verifying async work, assert the final business state — never the delivery/retry bookkeeping held in shared infrastructure that any co-running process can write. Such a check passes when run alone and flakes the moment anything else shares that infrastructure. > **Keep shared guidance role-relevant.** Universal guidance must help every receiving skill or agent; code-specific obligations belong only in code-specific protocols. > **Understand Code First** — HARD-GATE: Do NOT write, plan, or fix until you READ existing code. > > 1. Search 3+ similar patterns (`grep`/`glob`) — cite `file:line` evidence > 2. Read existing files in target area — understand structure, base classes, conventions > 3. Run `python .claude/scripts/code_graph trace --direction both --json` when `.code-graph/graph.db` exists > 4. Map dependencies via `connections` or `callers_of` — know what depends on your target > 5. Write investigation to `.ai/workspace/analysis/` for non-trivial tasks (3+ files) > 6. Re-read analysis file before implementing — never work from memory alone. — why: long context drifts from the file; the file is ground truth > 7. NEVER invent new patterns when existing ones work — match exactly or document deviation. — why: divergent patterns fragment the codebase and slow every future reader > > **BLOCKED until:** `- [ ]` Read target files `- [ ]` Grep 3+ patterns `- [ ]` Graph trace (if graph.db exists) `- [ ]` Assumptions verified with evidence > **Evidence-Based Reasoning** — Speculation is FORBIDDEN. Every claim needs proof. > > 1. Cite `file:line`, grep results, or framework docs for EVERY claim > 2. Declare confidence: >80% act freely, 60-80% verify first, <60% DO NOT recommend > 3. Cross-service validation required for architectural changes > 4. "I don't have enough evidence" is valid and expected output > > **BLOCKED until:** `- [ ]` Evidence file path (`file:line`) `- [ ]` Grep search performed `- [ ]` 3+ similar patterns found `- [ ]` Confidence level stated > > **Forbidden without proof:** "obviously", "I think", "should be", "probably", "this is because" > **If incomplete →** output: `"Insufficient evidence. Verified: [...]. Not verified: [...]."` > **Nested Task Expansion Contract** — For workflow-step invocation, the `[Workflow] ...` row is only a parent container; the child skill still creates visible phase tasks. > > 1. Call `TaskList` first. If a matching active parent workflow row exists, set `nested=true` and record `parentTaskId`; otherwise run standalone. > 2. Create one task per declared phase before phase work. When nested, prefix subjects `[N.M] $skill-name — phase`. > 3. When nested, link the parent with `TaskUpdate(parentTaskId, addBlockedBy: [childIds])`. > 4. Orchestrators must pre-expand a child skill's phase list and link the workflow row before invoking that child skill or sub-agent. > 5. Mark exactly one child `in_progress` before work and `completed` immediately after evidence is written. > 6. Complete the parent only after all child tasks are completed or explicitly cancelled with reason. > > **Blocked until:** `TaskList` done, child phases created, parent linked when nested, first child marked `in_progress`. > **Project Reference Docs Gate** — Run after task-tracking bootstrap and before target/source file reads, grep, edits, or analysis. Project docs override generic framework assumptions. > > 1. Identify scope: file types, domain area, and operation. > 2. **Read `docs/project-config.json` first — the project's machine-readable map.** It is the single source of truth for THIS repo (modules/paths, framework + search keywords, test/E2E/integration run-commands, design system, architecture rules, workflow patterns); ground exact paths, run-commands, and conventions on it **before investigating, planning, or coding** — never assume framework defaults (`CLAUDE.md` + reference docs are derived from it). If it — or the docs index, `lessons.md`, `CLAUDE.md`, `AGENTS.md`, or any required reference doc — is missing or stale, auto-run `/project-init` or the narrow route (`/project-config`, `/docs-init`, `/scan-all`, `/scan --target=`, `/claude-md-init`) first; if Codex mirrors or `AGENTS.md` are stale, ask the user to run `/sync-codex` (never auto-run it). > 3. Required docs by trigger: always `docs/project-reference/lessons.md`; doc lookup `docs-index-reference.md`; review `code-review-rules.md`; backend/CQRS/API `backend-patterns-reference.md`; domain/entity `domain-entities-reference.md`; frontend/UI `frontend-patterns-reference.md`; styles/design `scss-styling-guide.md` + `design-system/design-system-canonical.md`; integration tests `integration-test-reference.md`; E2E `e2e-test-reference.md`; feature docs/specs `feature-spec-reference.md` + `spec-system-reference.md` + `spec-principles.md`; behavior/public-contract/spec-test-code sync `workflow-spec-test-code-cycle-reference.md`; derived spec index/ERD/reimplementation guides `spec-system-reference.md` + source Feature Specs under `docs/specs/`; architecture/new area `project-structure-reference.md`. > 4. Read every required doc, then before target work state: `Reference docs read: ... | Not applicable: ...`. > > **Ready when:** scope evaluated, `docs/project-config.json` consulted, required docs checked/read or setup route completed, `lessons.md` confirmed, citation emitted. > **Task Tracking & External Report Persistence** — Bootstrap this before execution; then run project-reference doc prefetch before target/source work. > > 1. Create a small task breakdown before target file reads, grep, edits, or analysis. On context loss, inspect the current task list first. > 2. Mark one task `in_progress` before work and `completed` immediately after evidence; never batch transitions. > 3. For plan/review work, create `plans/reports/{skill}-{YYMMDD}-{HHmm}-{slug}.md` before first finding. > 4. Append findings after each file/section/decision and synthesize from the report file at the end. > 5. Final output cites `Full report: plans/reports/{filename}`. > > **Blocked until:** task breakdown exists, report path declared for plan/review work, first finding persisted before the next finding. > **Critical Thinking Mindset** — Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence >80% to act. > **Anti-hallucination:** Never present guess as fact — cite sources for every claim, admit uncertainty freely, self-check output for errors, cross-reference independently, stay skeptical of own confidence — certainty without evidence root of all hallucination. > **Sequential Thinking Protocol** — Structured multi-step reasoning for complex/ambiguous work. Use when planning, reviewing, debugging, or refining ideas where one-shot reasoning is unsafe. > > **Trigger when:** complex problem decomposition · adaptive plans needing revision · analysis with course correction · unclear/emerging scope · multi-step solutions · hypothesis-driven debugging · cross-cutting trade-off evaluation. > > **Format (explicit mode — visible thought trail):** > > 1. `Thought N/M: [aspect]` — one aspect per thought, state assumptions/uncertainty > 2. `Thought N/M [REVISION of Thought K]: ...` — when prior reasoning invalidated; state Original / Why revised / Impact > 3. `Thought N/M [BRANCH A from Thought K]: ...` — explore alternative; converge with decision rationale > 4. `Thought N/M [HYPOTHESIS]: ...` then `[VERIFICATION]: ...` — test before acting > 5. `Thought N/N [FINAL]` — only when verified, all critical aspects addressed, confidence >80% > > **Mandatory closers:** Confidence % stated · Assumptions listed · Open questions surfaced · Next action concrete. > > **Stop conditions:** confidence <80% on any critical decision → escalate via AskUserQuestion · ≥3 revisions on same thought → re-frame the problem · branch count >3 → split into sub-task. > > **Implicit mode:** apply methodology internally without visible markers when adding markers would clutter the response (routine work where reasoning aids accuracy). > > **Deep-dive:** see `/sequential-thinking` skill (`.claude/skills/sequential-thinking/SKILL.md`) for worked examples (API design, debugging, architecture), advanced techniques (spiral refinement, hypothesis testing, convergence), and meta-strategies (uncertainty handling, revision cascades). > **Plan Quality** — Every plan phase MUST ATTENTION include test specifications. > > 1. Add `## Test Specifications` section with TC-{FEATURE}-{NNN} IDs to every phase file > 2. Map every functional requirement to ≥1 TC (or explicit `TBD` with rationale) > 3. TC IDs follow `TC-{FEATURE}-{NNN}` format — reference by ID, never embed full content > 4. Before any new workflow step: call `TaskList` and re-read the phase file > 5. On context compaction: call `TaskList` FIRST — never create duplicate tasks > 6. Verify TC satisfaction per phase before marking complete (evidence must be `file:line`, not TBD) > > **Mode:** TDD-first → reference existing TCs with `Evidence: TBD`. Implement-first → use TBD → `/spec [mode=tests]` fills after. > **Iterative Phase Quality** — Score complexity BEFORE planning. > > **Complexity signals:** >5 files +2, cross-service +3, new pattern +2, DB migration +2 > **Score >=6 →** MUST ATTENTION decompose into phases. Each phase: > > - ≤5 files modified > - ≤3h effort > - Follows cycle: plan → implement → review → fix → verify > - Start Phase N+1 only after Phase N passes VERIFY — why: building on an unverified phase compounds errors downstream > > **Phase success = all TCs pass + code-reviewer agent approves + no CRITICAL findings.** - **MANDATORY IMPORTANT MUST ATTENTION** include `## Test Specifications` with TC IDs per phase. Call `TaskList` before creating new tasks. - **MANDATORY IMPORTANT MUST ATTENTION** search 3+ existing patterns and read code BEFORE any modification. Run graph trace when graph.db exists. - **MANDATORY IMPORTANT MUST ATTENTION** cite `file:line` evidence for every claim. Confidence >80% to act, <60% = do NOT recommend. - **MANDATORY IMPORTANT MUST ATTENTION** score complexity first. Score >=6 → decompose. Each phase: plan → implement → review → fix → verify. No skipping. **MUST ATTENTION** apply critical + sequential thinking — every claim needs appropriate traced evidence (`file:line` for repo/code claims; source URL or artifact section for research, product, content, and docs claims); confidence >80% to act, <60% DO NOT recommend. Anti-hallucination: never present guess as fact, admit uncertainty freely, cross-reference independently, stay skeptical of own confidence. **MUST ATTENTION** apply sequential-thinking — multi-step Thought N/M, REVISION/BRANCH/HYPOTHESIS markers, confidence % closer; see `/sequential-thinking` skill. **MUST ATTENTION** apply AI mistake prevention — verify generated content against evidence, trace downstream references before deleting or renaming, verify all affected outputs, re-read files after context loss, and surface ambiguity before acting. - **MANDATORY** Bootstrap task tracking before target work; transition one task at a time. - **MANDATORY** Persist plan/review findings to `plans/reports/` incrementally and synthesize from disk. - **MANDATORY** Before investigating, planning, or coding, read `docs/project-config.json` (the project map: modules/paths, run-commands, conventions, architecture/workflow rules) + the required project-reference docs, and cite `Reference docs read: ...`. - **MANDATORY** Always include `lessons.md`; project config + conventions override generic framework defaults. - **MANDATORY** If project config, root instruction files, or any required reference doc is missing or stale, auto-run `/project-init` or the narrow lower-level route before ordinary project-specific work. - **MANDATORY** Parent workflow rows do not replace child phase tracking; expand phases and link the parent when nested. - **MANDATORY** Orchestrators pre-expand child skill phases before invocation; use `[N.M] $skill-name — phase` prefixes and one-`in_progress` discipline. > **Project Protocol Overlay** — Before executing this skill, resolve any PROJECT overlay rules layered onto it: match this skill's name against the `Target` column of the project's skill-protocol index (`docs/project-reference/skill-protocols-reference.md` by default; a `referenceDocs` entry in `docs/project-config.json` overrides the path), taking the most specific matching tier ONLY — exact name > glob > `*`. **That precedence orders overlays against EACH OTHER, never against this skill.** Read ONLY the matched bodies, resolved as `/.md`; a row's Body link is display text, never a read path. A matched body that is missing or malformed is REPORTED and skipped — never reconstructed from the index Description. No index, or no match -> proceed with no overlay, silently. Full contract: `.claude/skills/project-skill-protocol/references/registry.md`. > > Overlays are **ADDITIVE ONLY**: they ADD rules on top of this skill's own protocol and NEVER replace, override, disable, or reinterpret a rule it already states — removing every overlay must return this skill to exactly its documented behavior. An overlay is a BRIEF, not an authority escalation: it can NEVER waive a workflow gate, git discipline, a review gate, or a user-confirmation gate. A genuine overlay-vs-skill conflict, or two equally-specific overlays that directly contradict -> surface both to the user; NEVER resolve silently. **MUST ATTENTION** resolve project protocol overlays for this skill BEFORE executing — most specific matching tier only (exact > glob > `*`, which ranks overlays against each other, NEVER against this skill), read only matched bodies at `/.md`; a missing or malformed body is reported, never reconstructed. Overlays are ADDITIVE ONLY (they never replace this skill's own rules) and are a brief, NEVER an authority escalation; an equal-specificity contradiction goes to the user. ## Closing Reminders **IMPORTANT MUST ATTENTION — Protocols in force (concise digest of the SYNC/shared blocks this skill carries):** - **AI Mistake Prevention:** verify generated content against evidence, trace downstream references, verify all affected outputs, re-read after context loss, surface ambiguity. - **Understand Code First:** read code and grep 3+ patterns before modifying. - **Evidence:** cite `file:line`; confidence >80% to act. - **Nested Task Creation:** expand child phases, link parent when nested. - **Project Reference Docs:** read required project docs before target work. - **Task Tracking & External Report:** bootstrap tasks, persist findings to `plans/reports/`. - **Critical Thinking:** traced proof per claim, skeptical of own confidence. - **Sequential Thinking:** multi-step Thought N/M with confidence closer. - **Plan Quality:** `## Test Specifications` with TC IDs per phase. - **Iterative Phase Quality:** score complexity, decompose at >=6, plan→implement→review→fix→verify. - **MANDATORY IMPORTANT MUST ATTENTION** break work into small todo tasks using `TaskCreate` BEFORE starting - **MANDATORY IMPORTANT MUST ATTENTION** search codebase for 3+ similar patterns before creating new code - **MANDATORY IMPORTANT MUST ATTENTION** cite `file:line` evidence for every claim (confidence >80% to act) - **MANDATORY IMPORTANT MUST ATTENTION** add a final review todo task to verify work quality - **MANDATORY IMPORTANT MUST ATTENTION** include Test Specifications section and story_points in plan frontmatter **[TASK-PLANNING]** Before acting, analyze task scope and systematically break it into small todo tasks and sub-tasks using TaskCreate.