Pdca

PDCA Skill

Unified Skill for managing PDCA cycle. Supports the entire Plan → Design → Do → Check → Act flow.

Arguments

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). 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). 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). 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). 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
   • QA_FAIL → fall back to iterate phase
   • QA_SKIP → mark qa as skipped, proceed to report
5. Complete predecessor Task first: Use TaskList to find the [Check] {feature} Task and the latest [Act-N] {feature} Task (and any earlier phase Task for this feature still in_progress) and TaskUpdate each to status: "completed" (see Phase Transition Rule). Then Create Task: [QA] {feature}
6. Update .bkit/state/pdca-status.json: phase = "qa", qaStatus = <PASS|FAIL|SKIP>

Output Path: docs/05-qa/{feature}.qa-report.md

Agent: bkit:qa-lead (mapped via frontmatter agents.qa)

iterate (Act Phase)

1. Check results (when matchRate < 90%)
2. Call pdca-iterator Agent
3. Auto-fix code based on Gap list
4. Auto re-run Check after fixes
5. Complete predecessor Task first: Use TaskList to find the [Check] {feature} Task and any prior [Act-*] {feature} Task for this feature still in_progress and TaskUpdate each to status: "completed" (see Phase Transition Rule). Then Create Task: [Act-N] {feature} (N = iteration count)
6. Stop when >= 90% reached or max iterations (5) hit

Iteration Rules:

• Max iterations: 5 (adjustable via bkit.config.json)
• Stop conditions: matchRate >= 90% or maxIterations reached