unclejobs-ai/second-claude-code/pdca

Iron Law

When a PDCA run is selected, honor its phase gates and transition order.

Red Flags

• "I can write tests later" → STOP. Write them now.
• "This change is too small to review" → STOP. Small bugs become P0 incidents.
• "I don't need to check previous cycle insights" → STOP. You will repeat the same mistake.
• "This is good enough" → STOP. Check the checklist.
• "No time to follow every step" → STOP. Skipped steps cost 3x more later.

PDCA — Knowledge Work Cycle Orchestrator

Meta-skill that runs the Plan → Do → Check → Act cycle. Each phase gates into the next. No gate skipping.

When to Use

• User wants end-to-end knowledge work (research + write + review + improve)
• User mentions a PDCA phase explicitly ("plan this", "check this")
• Complex work requiring multiple skills in sequence
• User says "알아보고 써줘", "research and write", or similar multi-phase requests

PDCA Is an Optional Orchestration Path

Use PDCA for end-to-end or explicitly phased work. Individual skills and commands such as /scc:research, /scc:write, /scc:review, and /scc:refine also run directly; they are not required to be wrapped in PDCA.

PDCA Cycle (when selected)
  ├─ Plan  → calls /scc:research (or domain research) + /scc:analyze
  ├─ Do    → calls the appropriate sub-skill based on output format
  │           └─ Supported format?     → /scc:write --format <format>
  ├─ Check → calls /scc:review (always, regardless of which sub-skill ran in Do)
  └─ Act   → calls /scc:refine or routes back to Plan/Do via Action Router

The key principle: PDCA owns transitions only for a PDCA run. It chooses a supported format and delegates production, then validates the resulting phase output.

Code Engineering Lane

When the task is code work (domain=code, repository edits, tests, debugging, CI, refactoring, or PR prep), PDCA still owns the Plan -> Do -> Check -> Act cycle, but it must load references/code-engineering-lane.md before planning. This lane absorbs the useful code-work discipline from external playbooks while preserving Second Claude's existing PDCA architecture.

The lane adds code-specific gates:

• Plan must produce executable acceptance criteria before medium or high-risk edits.
• Do should use branch/worktree isolation for non-trivial implementation and keep a stage report for long work.
• Check must separate worker output from validator/reviewer proof.
• Act must clean, simplify, and record handoff state before completion.

Use the lane as a specialization layer, not as a replacement for review, workflow, or loop.

Do-Phase Sub-Skill Selection

When PDCA enters the Do phase, it picks the most specialized sub-skill that matches the artifact format:

Key trigger keywords for sub-skill selection (PDCA scans the user's prompt and the Plan output's dod field):

• "뉴스레터", "newsletter" → /scc:write --format newsletter in Do
• "아티클", "article" → /scc:write --format article in Do
• "쇼츠", "shorts", "릴스", "Reels" → /scc:write --format shorts in Do
• "보고서", "report" → /scc:write --format report in Do
• "소셜", "social" → /scc:write --format social in Do
• "카드뉴스", "card news", "캐러셀" → /scc:write --format card-news in Do
• Anything else → /scc:write in Do

Why PDCA Wraps Sub-Skills (Doesn't Hand Off)

The Plan and Check phases add value that no sub-skill provides on its own:

• Plan adds upstream rigor: Question Protocol, source minimums, framework analysis, DoD definition. Without Plan, sub-skills work on whatever scope the user happened to specify, which is often incomplete.
• Check adds downstream rigor: Multi-reviewer parallel validation, fact-checking, structural analysis, cross-model review. Without Check, sub-skills self-approve their own output, which misses systematic blind spots.
• Act adds correction loop: Action Router classifies failures by root cause (research gap vs format gap vs polish gap) and routes back to the right phase. Without Act, the user has to manually decide what to fix.

A sub-skill running on its own = single-shot generation with the sub-skill's internal checks only. PDCA wrapping a sub-skill = upstream Plan rigor + sub-skill's internal pipeline + downstream Check + Act loop. Strictly more validation.

When an Optional External Capability Has Its Own Phases

An installed external plugin may expose a specialized capability with its own phases. If a caller explicitly invokes it, those phases are outside this plugin's built-in routing; PDCA can validate the returned artifact when it is used as Do input.

For the full sub-skill dispatch protocol (input contract, output contract, failure handling, integration points), see references/domain-pipeline-integration.md.

This means a full PDCA run on a newsletter looks like:

PDCA Plan  →  /scc:research + /scc:analyze (gather sources, build framework)
PDCA Do    →  /scc:write --format newsletter (research/review can be skipped when
              Plan and Check are owned by this PDCA run)
PDCA Check →  /scc:review (parallel reviewers; this is the independent Check phase)
PDCA Act   →  Action Router classifies any Check findings and routes to Plan,
              Do, or Refine

PDCA's Check is independent of any review a caller or optional external capability may have performed. It supplies the cycle's configured consensus verdict.

Past Failure That Motivated This Architecture

The lesson: PDCA adds value when the user needs phase gates and routed correction. It is not a requirement for every direct skill invocation, and this plugin does not assume unavailable specialized commands.

Phase Detection

When a single phase is detected, run that phase and pause at its gate. When full PDCA is detected, run all phases with gates between each.

Architecture

User Prompt → normal Claude Code skill/command selection
 
PDCA Orchestrator
│
├── PLAN (research → analyze)
│   ├── Question Protocol (max 3 Qs → unanswered = save assumptions)
│   ├── Eevee (researcher): data collection
│   └── Alakazam (analyst) + Mewtwo (strategist): structured analysis
│       └── Gate: Brief + Analysis exist? Runtime source-count gate (≥5)
│
├── DO (pure execution)
│   └── Smeargle (writer): /scc:write --skip-research --skip-review
│       └── Gate: Artifact complete? Format OK?
│
├── CHECK (unchanged)
│   └── Xatu + Absol + Porygon + Jigglypuff + Unown: /scc:review
│       └── Gate: Verdict routing
│
└── ACT (action router → refine)
    ├── Action Router (root cause classification)
    │   ├── SOURCE/ASSUMPTION/FRAMEWORK → PLAN
    │   ├── COMPLETENESS/FORMAT → DO
    │   └── EXECUTION_QUALITY → REFINE
    └── Ditto (editor): /scc:refine
        └── Gate: Target met? → EXIT

Phase Output Schemas

Each phase outputs a validated schema before the gate is passed. See references/phase-schemas.md for full field rules and validation failure actions. Missing required fields are gate failures, not warnings.

Phase Gates

Load the relevant checklist from references/ at each transition. Gates are mandatory — do NOT skip.

Permission pattern: read-only (plan) → write (acceptEdits) → read-only → write. Switch at every phase boundary.

Check → Act routing: APPROVED → EXIT | MINOR FIXES → Act light touch | NEEDS IMPROVEMENT → Act full refine | MUST FIX → Act critical-first. Preset reviewer counts and optional quality checks remain defined by /scc:review; not every narrative contract is enforced by the state MCP runtime.

Cycle limit: If cycle_count >= max_cycles, do NOT start another cycle. Notify: "max_cycles에 도달했습니다 — 현재 결과물로 종료합니다." Exit with best artifact.

Worktree: Do artifacts written in worktree-pdca-do. If Check returns MUST FIX, orchestrator discards the worktree for a clean restart.

Workflow (Full PDCA)

1. Plan: Question Protocol → research (Eevee) → analyze (Alakazam + Mewtwo) → EnterPlanMode (brief user) → ExitPlanMode (get approval). On rejection: re-run with feedback.
2. Gate: brief + analysis quality + Plan Mode approval.
3. Do: write (Smeargle) --skip-research --skip-review using Plan artifacts.
4. Gate: artifact completeness.
5. Check: review (Xatu, Absol, Porygon, Jigglypuff, Unown) with appropriate preset.
6. Gate: verdict → Act or Exit.
7. Act: Action Router → Plan / Do / Loop.
8. Gate: target met → Exit or present options.

Options

Note: --constraints is a write-skill flag passed through by the orchestrator (see do-phase.md, act-phase.md).

Stuck Detection

Run at every phase transition. See references/stuck-detection.md for full signal definitions, root causes, and remediation steps.

If both stuck patterns and max_cycles trigger simultaneously, report both and exit with the best artifact.

State

State persisted in .data/state/pdca-active.json. See references/state-schema.md for full schema, field definitions, and single-active-run constraint.

MCP tools (when pdca-state server is available): pdca_get_state, pdca_start_run, pdca_transition, pdca_check_gate, pdca_update_stuck_flags, pdca_end_run.

Output

At each gate: phase summary + gate verdict (pass/fail + reason) + next phase recommendation.

At cycle end: full artifact chain, Action Router decisions, verdict progression, total phases + token cost estimate.

Notifications