# Work Pdca Loop

> Create and maintain repo-local PDCA goal-loop work folders with decision points, state history archives, restart prompts, and visual status dashboards. Use when the user asks to create, organize, continue, audit, visualize, or standardize work/ task folders with non-linear execution and durable state history.

- Skill: `dwsy/work-pdca-loop` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add dwsy/work-pdca-loop`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dwsy/work-pdca-loop/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: Dwsy (https://skillmd.com/u/dwsy)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/dwsy/work-pdca-loop

---


# Work PDCA Loop

Use this skill for repo-local `work/` task folders that must be easy to sort, resume, audit, visualize, and hand off.

This is not a static template. It models work as a PDCA loop:

1. `Plan`: frame objective, constraints, acceptance, and decision criteria.
2. `Do`: execute the smallest tracer path that can produce evidence.
3. `Check`: compare evidence against acceptance, risks, and regressions.
4. `Act`: close, continue, or pivot based on recorded decisions.

Execution must not be purely linear. Decision points such as `D1` and `D2` determine whether to continue, split, research, pivot, or close.

## Directory Rule

Use this folder shape:

```text
work/YYYYMMDD-short-slug/
```

Examples:

```text
work/20260706-dyncode-sync-event-listener-goal/
work/20260706-cache-projection-research/
```

Rules:

- `YYYYMMDD` is an eight-digit date.
- Prefer the date when the task folder is created.
- Preserve historical dates when existing state or docs prove them.
- Use lowercase kebab-case for the slug.
- Do not create undated `work/<slug>/` folders for new work.

## Required Files

Every PDCA goal-loop folder should contain:

```text
task.md
pdca.md
decisions.md
prompt.md
state.json
history/events.jsonl
history/state/*.json
```

Meanings:

- `task.md`: objective, scope, out-of-scope, acceptance.
- `pdca.md`: cycle stage intent and evidence.
- `decisions.md`: human-readable decision map.
- `prompt.md`: restart instructions.
- `state.json`: current machine-readable state.
- `history/state/*.json`: archived snapshots before each state change.
- `history/events.jsonl`: append-only state change log.

## State Contract

`state.json` should include these core fields. Extra task-specific fields are allowed.

```json
{
  "schema_version": "work-pdca-loop.v1",
  "project_root": "",
  "work_dir": "",
  "title": "",
  "objective": "",
  "status": "in_progress",
  "mode": "pdca_goal_loop",
  "pdca": {
    "cycle": 1,
    "stage": "plan",
    "stages": []
  },
  "current_phase": "P0",
  "created_at": "",
  "updated_at": "",
  "owner": "codex",
  "scope": [],
  "tags": [],
  "ssot": [],
  "inputs": [],
  "outputs": [],
  "phases": [],
  "decision_points": [],
  "validation": {
    "passed": false,
    "commands": [],
    "notes": ""
  },
  "history": {
    "state_snapshots": "",
    "events": ""
  },
  "risks": [],
  "next_action": "",
  "notes": ""
}
```

Recommended `status` values: `planned`, `in_progress`, `completed`, `withdrawn`, `blocked`.

Recommended `pdca.stage` values: `plan`, `do`, `check`, `act`.

## Decision Points

Decision points are first-class state, not prose only.

Example shape:

```json
{
  "id": "D1",
  "phase": "D1",
  "question": "Which route should the next implementation take?",
  "status": "open",
  "options": [
    {
      "id": "direct",
      "label": "Direct implementation",
      "next_phase": "P2",
      "criteria": "Scope is clear, blast radius is small, and validation path is known."
    }
  ],
  "selected_option_id": null,
  "rationale": "",
  "decided_at": null
}
```

Do not move past a decision phase without recording:

- selected option
- rationale
- next phase
- timestamp

## Generator

Prefer the bundled PDCA generator for new folders:

```bash
bun ~/.agents/skills/work-pdca-loop/scripts/create-pdca-goal.mjs \
  --project-root /path/to/project \
  --work-root work \
  --slug dyncode-sync-event-listener-goal \
  --title "Dyncode Sync Event Listener Goal" \
  --objective "Design and implement sync table listener registration." \
  --date 20260706
```

Package script form inside this skill directory:

```bash
bun run create -- --project-root /path/to/project --work-root work --slug dyncode-sync-event-listener-goal --title "Dyncode Sync Event Listener Goal" --objective "Design and implement sync table listener registration."
```

The script fails if the target folder already exists. It creates required files, an initial `state.json`, an initial state snapshot, and a creation event.

## State Updates

Do not edit `state.json` by blind overwrite when changing status. Use the update script so old state is archived first.

```bash
bun ~/.agents/skills/work-pdca-loop/scripts/update-pdca-state.mjs \
  --work-dir /path/to/project/work/20260706-dyncode-sync-event-listener-goal \
  --status in_progress \
  --phase D1 \
  --pdca-stage check \
  --next-action "Select implementation route after evidence review." \
  --event "phase_changed"
```

Select a decision branch:

```bash
bun ~/.agents/skills/work-pdca-loop/scripts/update-pdca-state.mjs \
  --work-dir /path/to/project/work/20260706-dyncode-sync-event-listener-goal \
  --decision-id D1 \
  --select-option direct \
  --rationale "Scope is clear and validation command is known." \
  --pdca-stage check \
  --event "decision_selected"
```

Update behavior:

1. Read current `state.json`.
2. Archive it to `history/state/<timestamp>.json`.
3. Apply requested changes.
4. Atomically write new `state.json`.
5. Append event to `history/events.jsonl`.

## Status Web UI (Solid.js)

Build the Solid dashboard once, then run the Bun server (serves `webui-solid/dist`):

```bash
bun run webui:build
bun run webui -- --project-root /path/to/project --work-root work --port 8787
```

Open `http://127.0.0.1:8787`.

Development (API + Vite，推荐一条命令):

```bash
bun run webui:dev --
# 或指定项目根：PDCA_PROJECT_ROOT=/path/to/project bun run webui:dev
```

`webui:dev` 会同时启动 Bun API（默认 8787）并把 Vite 5173 的 `/api` 代理过去。**不要**只跑 `cd webui-solid && bun run dev`，否则 `/api/decisions/open` 会 404。

手动双终端：

```bash
bun run webui -- --project-root /path/to/project --port 8787
WEBUI_API_PORT=8787 bun run webui:dev:vite-only
```

The console scans `work/*/state.json` and provides:

- overview KPIs, PDCA stage board, TanStack task table
- decision inbox and cross-task timeline (`history/events.jsonl`)
- task workbench: phases, decisions, events, snapshots, markdown files (read-only)
- project switching via Settings (`projectRoot` / `workRoot` query + localStorage)
- light/dark theme

REST: `/api/workspaces` (GET/POST/DELETE), `/api/status`, `/api/decisions/open`, `/api/timeline`, `/api/tasks/{workDir}`, …

**多工作区：** CLI（`create` / `update`）与 `webui` 启动时会注册 `projectRoot+workRoot` 到 `~/.config/work-pdca-loop/workspaces.json`；控制台顶栏可切换。环境变量 `WORK_PDCA_REGISTRY` 可改注册表路径。

Project paths may use `~`. Passing `/path/to/project/work` is normalized to project root plus `workRoot=work`. Custom state schemas still work when compatible fields exist (`objective`, `current_phase`, `phases`, `decision_points`, validation).

## Maintenance Checklist

- Keep `state.json.status`, `state.json.pdca.stage`, and `state.json.next_action` current.
- Use `update-pdca-state.mjs` for state changes so history is preserved.
- Record validation commands after they run.
- Record decision option and rationale before crossing decision phases.
- Update references when a folder is renamed.
- When a task is withdrawn, keep `status: "withdrawn"` and explain why.
- Do not mark a broad goal complete unless current evidence proves all required work.