pdca

# PDCA Skill > Unified Skill for managing PDCA cycle. Supports the entire Plan → Design → Do → Check → Act flow. ## Arguments | Argument | Description | Example | |----------|-------------|---------| | `pm [feature]` | Run PM Agent Team analysis (pre-Plan) | `/pdca pm user-auth` | | `plan [feature]` | Create Plan document | `/pdca plan user-auth` | | `design [feature]` | Create Design document | `/pdca design user-auth` | | `do [feature]` | Do phase guide (start implementation) | `/pdca do user-auth` | | `analyze [feature]` | Run Gap analysis (Check phase) | `/pdca analyze user-auth` | | `iterate [feature]` | Auto improvement iteration (Act phase) | `/pdca iterate user-auth` | | `qa [feature]` | Run QA phase (L1-L5 tests) | `/pdca qa user-auth` | | `report [feature]` | Generate completion report | `/pdca report user-auth` | | `archive [feature]` | Archive completed PDCA documents | `/pdca archive user-auth` | | `cleanup [feature]` | Cleanup archived features from status | `/pdca cleanup` | | `team [feature]` | Start PDCA Team Mode (requires Agent Teams) | `/pdca team user-auth` | | `team status` | Show Team status | `/pdca team status` | | `team cleanup` | Cleanup Team resources | `/pdca team cleanup` | | `status` | Show current PDCA status | `/pdca status` | | `next` | Guide to next phase | `/pdca next` | ## Action Details ### pm (PM Analysis Phase) Run PM Agent Team for product discovery and strategy analysis before Plan phase. 1. **Call pm-lead Agent** (orchestrates 4 sub-agents) 2. pm-lead runs Phase 1: Context Collection (project info, git history) 3. pm-lead runs Phase 2: Parallel Analysis (3 agents simultaneously) - pm-discovery: Opportunity Solution Tree (Teresa Torres) - pm-strategy: Value Proposition (JTBD 6-Part) + Lean Canvas - pm-research: 3 Personas + 5 Competitors + TAM/SAM/SOM 4. pm-lead runs Phase 3: PRD Synthesis via pm-prd agent - Beachhead Segment (Geoffrey Moore) + GTM Strategy - 8-section PRD generation 5. Output PRD to `docs/00-pm/{feature}.prd.md` 6. Create Task: `[PM] {feature}` 7. Update `.bkit/state/pdca-status.json`: phase = "pm" 8. Guide user to next step: `/pdca plan {feature}` **Output Path**: `docs/00-pm/{feature}.prd.md` **Requirements**: - Agent Teams enabled: `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` - Project level: Dynamic or Enterprise (Starter not supported) ### plan (Plan Phase) 0. **Template Loading**: Read `templates/plan.template.md` to understand the required Plan document structure and sections. Use this template's sections as your document outline. This is MANDATORY — do not generate Plan documents from memory or assumptions. 1. **PRD Auto-Reference**: Check if `docs/00-pm/{feature}.prd.md` exists - If found: Read PRD and use as context for Plan document (improves quality significantly) - If not found: Proceed normally (tip: run `/pdca pm {feature}` first for better results) 2. Check if `docs/01-plan/features/{feature}.plan.md` exists 3. If not, create based on `plan.template.md` 4. If exists, display content and suggest modifications 5. **Checkpoint 1 — Requirements Confirmation**: Present understanding of the feature (problem, scope, constraints) and use AskUserQuestion: "요구사항 이해가 맞나요? 빠진 건 없나요?" Wait for user confirmation before proceeding. 6. **Checkpoint 2 — Clarifying Questions**: Identify underspecified elements (edge cases, error handling, integration points, compatibility). Present organized question list. Wait for answers before generating the document. 7. Generate Plan document with user-confirmed requirements 8. **Complete predecessor Task first**: If a `[PM] {feature}` Task exists and is still `in_progress`, use TaskList to find it and TaskUpdate it to `status: "completed"` before creating the Plan Task (see [Phase Transition Rule](#task-integration)). Then Create Task: `[Plan] {feature}` 9. Update `.bkit/state/pdca-status.json`: phase = "plan" 10. Write `## Executive Summary` at document top with 4-perspective table (Problem/Solution/Function UX Effect/Core Value), each 1-2 sentences 11. **Context Anchor Generation**: After generating Plan document, extract Context Anchor (WHY/WHO/RISK/SUCCESS/SCOPE) from Executive Summary, Requirements, and Risk sections. Write as `## Context Anchor` table between Executive Summary and Section 1. This anchor propagates to Design/Do documents for cross-session context continuity. 12. **MANDATORY**: After completing the document, also output the Executive Summary table in your response so the user sees it immediately without opening the file **Output Path**: `docs/01-plan/features/{feature}.plan.md` > **Tip**: For features with ambiguous requirements or multiple implementation approaches, > use `/plan-plus {feature}` instead. Plan Plus adds brainstorming phases (intent discovery, > alternatives exploration, YAGNI review) before document generation for higher-quality plans. ### design (Design Phase) 0. **Template Loading**: Read `templates/design.template.md` to understand the required Design document structure. Use this template's sections as your document outline. This is MANDATORY — do not generate Design documents from memory or assumptions. 1. Verify Plan document exists (required - suggest running plan first if missing) 2. Read Plan document to understand requirements and scope 3. **PRD Context Loading**: Check if `docs/00-pm/{feature}.prd.md` exists. If found, read the Executive Summary and Beachhead/GTM sections to inform architecture decisions with market context. This prevents strategic context loss at the Plan→Design handoff. 4. **Context Anchor Embed**: Copy Plan's `## Context Anchor` table to Design document top (between header metadata and ## 1. Overview). If Plan has no Context Anchor (legacy), skip this step gracefully. 5. **Generate 3 Architecture Options** (inspired by feature-dev Phase 4): - **Option A — Minimal Changes**: Least modification, maximum reuse of existing code. Fast but potentially coupled. - **Option B — Clean Architecture**: Best separation of concerns, most maintainable. More files, more refactoring. - **Option C — Pragmatic Balance**: Good boundaries without over-engineering. Recommended default. 6. Present comparison table with trade-offs (complexity, maintainability, effort, risk) 7. **Checkpoint 3 — Architecture Selection**: Use AskUserQuestion: "3가지 설계안 중 어떤 걸 선택하시겠습니까?" Include recommendation. Wait for user selection. 8. Create `docs/02-design/features/{feature}.design.md` using selected architecture 9. Use `design.template.md` structure + reference Plan content 10. **Session Guide Generation**: Analyze Design's `## 11. Implementation Guide` structure to generate Module Map and Recommended Session Plan. Add as `### 11.3 Session Guide` within Implementation Guide section. This enables `/pdca do {feature} --scope module-N` for multi-session incremental implementation. 11. **Design Anchor Integration (Pencil MCP)**: If the feature involves UI and Pencil MCP is available: - Suggest: "UI 컨셉 페이지를 1-2개 먼저 만든 후 `/design-anchor capture {feature}` 로 디자인 토큰을 잠그세요" - If Design Anchor already exists (`docs/02-design/styles/{feature}.design-anchor.md`), embed it in the Design document as `## Design Anchor` section - This ensures design tokens (colors, typography, spacing) are locked before implementation 12. **Complete predecessor Task first**: Use TaskList to find the `[Plan] {feature}` Task (and any earlier phase Task for this feature still `in_progress`) and TaskUpdate each to `status: "completed"` — this resolves the `blockedBy` chain and prevents stale phase status from leaking into prompt context (see [Phase Transition Rule](#task-integration)). Then Create Task: `[Design] {feature}` (blockedBy: Plan task) 13. Update `.bkit/state/pdca-status.json`: phase = "design" **Output Path**: `docs/02-design/features/{feature}.design.md` ### do (Do Phase) 1. Verify Design document exists (required) 2. **Read Design document FULLY** (read the entire document, not just a summary. This is critical — full context reload ensures each session starts with complete architectural context) 3. **Full Upstream Context Loading (Phase 2+3)**: Load the COMPLETE upstream document chain: - Read PRD (`docs/00-pm/{feature}.prd.md`) — extract WHY context (JTBD, value proposition, market positioning) - Read Plan (`docs/01-plan/features/{feature}.plan.md`) — extract Context Anchor, Success Criteria, Requirements - This ensures implementation decisions are guided by strategic intent from PRD→Plan→Design, not just the Design spec 4. **Decision Record Chain Display**: Extract and display key decisions from PRD→Plan→Design as a unified chain. Format: ``` 📋 Decision Record Chain [PRD] Target: {market/user segment} — {rationale} [Plan] Architecture: {selected option} — {rationale} [Design] State Mgmt: {selected approach} — {rationale} ``` 5. **Success Criteria Tracking**: Extract Success Criteria from Plan document. Display as implementation checklist — each criterion must be addressed during implementation. Mark criteria that are covered by the current --scope. 6. **Parse --scope parameter**: If arguments contain `--scope <value>`, extract module list (comma-separated scope keys). Match against Design's Session Guide Module Map. Filter implementation items to show only matching modules. 7. **Display Context Anchor**: Show the Context Anchor table from Design document header. Format: "📌 Context Anchor" + WHY/WHO/RISK/SUCCESS/SCOPE table. This reminds the user WHY we're building this feature. 8. **Session Guide Display**: - If no --scope: Show full Module Map from Design + recommend session split + proceed with full implementation guide - If --scope provided: Show only the selected modules' implementation items 9. Summarize implementation scope: - Files to create: N - Files to modify: M - Estimated changes: ~X lines 10. **Checkpoint 4 — Implementation Approval**: Present scope summary and use AskUserQuestion: "이 범위로 구현을 시작해도 되겠습니까?" **DO NOT START IMPLEMENTATION WITHOUT USER APPROVAL.** 11. After approval, provide implementation guide based on `do.template.md` 12. Reference implementation order from Design document (filtered by --scope if provided) 13. **Code Comment Convention (Phase 3)**: During implementation, add Design reference comments for key architectural decisions: - At module/file level: `// Design Ref: §{section} — {decision rationale}` - At critical logic: `// Plan SC: {success criteria being addressed}` - These comments create traceable links from code back to design decisions 14. **Complete predecessor Task first**: Use TaskList to find the `[Design] {feature}` Task (and any earlier phase Task for this feature still `in_progress`) and TaskUpdate each to `status: "completed"` — this resolves the `blockedBy` chain and prevents stale phase status from leaking into prompt context (see [Phase Transition Rule](#task-integration)). Then Create Task: `[Do] {feature}` (blockedBy: Design task) 15. Update `.bkit/state/pdca-status.json`: phase = "do" **--scope Parameter**: ``` /pdca do feature # Full scope (backward compatible) + session guide /pdca do feature --scope module-1 # Only module-1 /pdca do feature --scope module-1,module-2 # Multiple modules ``` **Guide Provided**: - Context Anchor (WHY/WHO/RISK/SUCCESS/SCOPE) - Session scope (filtered or full) - Implementation order checklist - Key files/components list - Dependency installation commands ### analyze (Check Phase) 1. Verify Do completion status (implementation code exists) 2. **Full Upstream Context Loading (Phase 2+3)**: Load the COMPLETE upstream document chain for comprehensive evaluation: - Read PRD (`docs/00-pm/{feature}.prd.md`) — verify strategic alignment (was the right problem solved?) - Read Plan (`docs/01-plan/features/{feature}.plan.md`) — verify Requirements fulfillment + Success Criteria - Read Design (`docs/02-design/features/{feature}.design.md`) — verify structural implementation match - This 3-layer verification catches gaps that single-document comparison misses 3. **Context Anchor Embed**: Copy Context Anchor from Design to Analysis document header. 4. **Strategic Alignment Check (Phase 3)**: Before structural gap analysis, verify: - Does the implementation address the PRD's core problem (WHY)? - Are Plan Success Criteria met or on track? - Were key Design decisions (architecture, data model, API) followed? - Flag strategic misalignments as Critical regardless of structural match rate 5. **Plan Success Criteria Reference**: Evaluate each Success Criteria from Plan: - Mark as ✅ Met / ⚠️ Partial / ❌ Not Met - Include evidence (file:line or test result) - Criteria violations are automatically Critical severity 6. **Call gap-detector Agent** (v2.3.0: Static Analysis + Runtime Verification Plan) - gap-detector performs static analysis (Structural + Functional + Contract) - gap-detector outputs a **Runtime Verification Plan** (L1/L2/L3 test specs) 7. Compare Design document vs implementation code on 3 static axes: - **Structural Match**: File existence, route coverage, component list - **Functional Depth**: Placeholder detection, Page UI Checklist verification, actual logic completeness - **API Contract**: 3-way verification (Design §4 ↔ Server route.ts ↔ Client fetch calls) 8. **Runtime Verification (v2.3.0)**: After gap-detector completes, execute runtime tests. - **Preferred**: Run existing tests from `tests/e2e/{feature}.spec.ts` (written during Do phase) - **Fallback**: If no test file exists, generate from gap-detector's Runtime Verification Plan - Test scenarios are defined in Design §8 Test Plan, implemented during Do phase, executed here **L1 — API Endpoint Tests** (always run if server is available): - Execute each curl command from gap-detector's L1 plan - Check: HTTP status code matches expected - Check: Response JSON shape matches expected (has .data, .error, .pagination) - Check: Auth guard returns 401 for protected endpoints - Check: Zod validation returns 400 with fieldErrors for invalid input - Check: Rate limiting returns 429 after threshold - Detect server: `curl -s -o /dev/null -w "%{http_code}" http://localhost:3000/` - If no server running: skip L1, warn user, use static-only formula **L2 — UI Action Tests** (run if Playwright is installed): - Generate Playwright test file from gap-detector's L2 plan - Write to `tests/e2e/{feature}-actions.spec.ts` - Run: `npx playwright test tests/e2e/{feature}-actions.spec.ts` - Each test: navigate to page → perform action → assert result - Check: API calls triggered by UI match expected endpoints - If Playwright not installed: skip L2, suggest `pnpm add -D @playwright/test` **L3 — E2E Scenario Tests** (run if Playwright is installed): - Generate Playwright test file from gap-detector's L3 plan - Write to `tests/e2e/{feature}-e2e.spec.ts` - Run: `npx playwright test tests/e2e/{feature}-e2e.spec.ts` - Full user journey: multi-page flows with state persistence - Check: complete flow from start to end without errors **Match Rate Formula (v2.3.0)**: ``` If runtime executed: Overall = (Structural × 0.15) + (Functional × 0.25) + (Contract × 0.25) + (Runtime × 0.35) If static only (no server): Overall = (Structural × 0.2) + (Functional × 0.4) + (Contract × 0.4) ``` 9. Calculate Match Rate and generate Gap list. Report all rates separately. 10. **Decision Record Verification (Phase 3)**: Check if key decisions from Decision Record Chain were followed in implementation. Flag deviations. 11. **Checkpoint 5 — Review Decision**: Present issues by severity (Critical/Important only, confidence ≥80%). Use AskUserQuestion with options: - "지금 모두 수정" — proceed to iterate - "Critical만 수정" — iterate critical only - "그대로 진행" — accept current state Wait for user decision before proceeding. 12. **Complete predecessor Task first**: Use TaskList to find the `[Do] {feature}` Task (and any earlier phase Task for this feature still `in_progress`) and TaskUpdate each to `status: "completed"` — this resolves the `blockedBy` chain and prevents stale phase status from leaking into prompt context (see [Phase Transition Rule](#task-integration)). Then Create Task: `[Check] {feature}` (blockedBy: Do task) 13. Update `.bkit/state/pdca-status.json`: phase = "check", matchRate **Output Path**: `docs/03-analysis/{feature}.analysis.md` ### qa (QA Phase) 1. Verify Iterate completion (Match Rate ≥ target or max iterations reached) 2. **Delegate to qa-phase skill**: Invoke the standalone `/qa-phase {feature}` skill, which owns L1-L5 test planning, generation, execution, and reporting. 3. The qa-phase skill: - Reads Design doc §8 Test Plan - Calls `qa-test-planner` to refine L1-L5 test specs - Calls `qa-test-generator` to emit runnable test files - Executes L1 (API) / L2 (UI actions) / L3 (E2E) tests via Chrome MCP - Optional L4 (perf) / L5 (security) for Enterprise level 4. Emit one of: - `QA_PASS` → auto-advance to `report` phase