agent-poka-yoke/SKILL.md

---
name: agent-poka-yoke
description: "Poka-yoke guardrails for AI agents — prevent errors before they happen through compositional validation, pre-flight checks, post-action verification, and least-privilege enforcement."
version: 1.0.0
author: Hermes Agent
license: MIT
platforms: [linux, macos, windows]
metadata:
  hermes:
    tags: [poka-yoke, mistake-proofing, guardrails, error-prevention, validation, agent-safety]
    related_skills: [systematic-debugging, test-driven-development, plan]
---

# Agent Poka-Yoke — Mistake-Proofing for AI Agents

## Overview

**Poka-yoke (ポカヨケ)** — японский термин из Toyota Production System: дизайн, который физически не позволяет совершить ошибку. Штырь в разъёме USB-A, который не воткнуть не той стороной.

В AI-агенте poka-yoke = **каскад проверок, который не даёт выполнить невалидное действие**. Не «посоветуй быть осторожным» — «заблокируй, если schema не проходит».

**Core principle:** Trust nothing. Validate everything. Catch errors BEFORE they cause damage, not after.

**Violating this skill is violating the architecture of reliable agent operations.**

---

## The Compositional Guardrails Architecture

No single tool solves safe execution end-to-end. The winning approach is **compositional** — multiple layers, each catching what the previous missed:

```
User request
  ↓
┌─────────────────────┐
│ LAYER 1: Policy     │ ← What can the agent DO? (permissions, boundaries)
└─────────┬───────────┘
          ↓
┌─────────────────────┐
│ LAYER 2: Pre-flight │ ← Is this SPECIFIC action SAFE? (context, state, GPU check)
└─────────┬───────────┘
          ↓
┌─────────────────────┐
│ LAYER 3: Schema     │ ← Are the PARAMETERS valid? (types, ranges, required)
└─────────┬───────────┘
          ↓
     [ TOOL EXECUTION ]
          ↓
┌─────────────────────┐
│ LAYER 4: Post-action│ ← Did the action succeed? (health-check, status, rollback)
└─────────┬───────────┘
          ↓
     Result to user
```

Each layer independently blocks bad outcomes. If one fails, the next catches it.

---

## The Four Guardrails Layers

### Layer 1: Policy (Permissions & Boundaries)

**What:** Defines what the agent is ALLOWED to do. Set at session/project level.

**Rules:**
1. **GPU Immunity** — Never touch GPU processes. Never kill GPU processes. Never start GPU processes. (Absolute rule, no exceptions.)
2. **Least Privilege** — The agent only has access to what is necessary for the current task.
3. **Identity Separation** — Agent uses its own credentials, not the user's identity. (For infrastructure: use service tokens, not user tokens, when possible.)
4. **Project Scope** — Agent operates only within the declared project boundary.

**How to enforce:**
```
Before ANY tool call, check:
  ✓ Is this action within project scope?
  ✓ Is this action within agent permissions?
  ✓ Is this action NOT touching GPU?
```

---

### Layer 2: Pre-flight Check

**What:** Validates the SPECIFIC action before execution.

**Every tool call MUST pass this checklist:**

#### 2a. Access Verification

Before calling any external API or service:
```
1. Can I reach the target? (server reachable, port open, auth valid)
2. Do I have the right credentials/tokens?
3. Does the target resource exist?
```

**For Coolify API:**
```bash
curl -s http://192.168.1.230:8000/api/v1/ping -H "Authorization: Bearer $COOLIFY_TOKEN"
```
Only proceed if ping succeeds.

**For Twenty CRM (MCP):**
```
Before any GraphQL query:
  ✓ MCP connection active?
  ✓ Object exists in schema?
```

**For databases (Postgres, Dragonfly, ClickHouse):**
```
Before any query:
  ✓ Connection string valid?
  ✓ Target DB exists?
  ✓ User has required privileges?
```

#### 2b. GPU Guardrail (Absolute)

Before ANY `terminal` or `browser` call:
```
IF command contains: nvidia-smi, kill -9, pkill, rm -rf, docker rm -f
  → Check if GPU-related: nvcc, nvidia, cuda, GPU, vram
  → IF GPU-related → BLOCK. Report to user. DO NOT PROCEED.
```

This is the most important guardrail. It must be checked EVERY TIME.

#### 2c. Irreversible Action Gate

Before destructive operations:
```
Operations that are irreversible or high-risk:
  - DELETE, remove, drop, truncate
  - Deploy to production
  - Change infrastructure config
  - Transfer funds/data

ACTION REQUIRED:
  1. Show user exactly what will happen
  2. Wait for explicit confirmation
  3. Only then proceed
```

#### 2d. Parameter Sanity Check

Before tool calls with arguments:
```
Required parameters present?
Types correct? (strings, not numbers; booleans, not strings)
Values in valid ranges?
No SQL injection patterns in strings?
No path traversal (../) in file paths?
```

---

### Layer 3: Schema Validation

**What:** Every tool call's arguments are validated against a strict schema BEFORE execution.

**Pattern:**
```python
# Every tool call is wrapped in validation:
def validate_call(tool_name: str, params: dict) -> ValidationResult:
    schema = get_schema(tool_name)  # Defined per tool
    try:
        validate(params, schema)
        return ValidationResult(passed=True)
    except ValidationError as e:
        return ValidationResult(passed=False, errors=[str(e)])
```

**For Coolify API calls:**
```
Required fields for service update:
  - uuid: valid UUID format
  - All other fields: correct types per API schema
  - FQDN: valid hostname pattern

If validation fails → self-repair (fix params) → retry ONCE.
If still fails → alert user with exact validation errors.
```

**For Twenty CRM GraphQL queries:**
```
Required: valid field names from Twenty schema
Types: match schema (ID, String, Boolean, Int, DateTime)
No unknown fields
No circular references in nested queries
```

**For terminal commands:**
```
No dangerous patterns: rm -rf /, > /dev/sda, dd if=...
Path exists before read operations
Command is a known, safe command
```

---

### Layer 4: Post-Action Verification

**What:** After EVERY significant action, verify the result before proceeding.

**Pattern:**
```
Action executed → Check result → If failed → Decide: rollback, retry, or alert
```

#### 4a. Coolify Operations

After deploy/restart/stop:
```
1. GET /api/v1/resources/{uuid} → check status
2. Status must be "Running" (for deploy) or "Stopped" (for stop)
3. If wrong status → alert user, suggest recovery
4. If unexpected status → do NOT proceed with dependent actions
```

#### 4b. Terminal Operations

After command execution:
```
1. Check exit code (must be 0 for success)
2. If exit code != 0:
   - Read stderr
   - Determine if self-repairable
   - If yes → fix and retry once
   - If no → report error, stop
3. For long commands → verify expected output patterns
```

#### 4c. Database Operations

After INSERT/UPDATE/DELETE on ClickHouse, Dragonfly, Postgres:
```
1. Verify affected rows > 0 (for write operations)
2. Verify no errors in response
3. For migrations → run a SELECT to confirm schema change
4. For cache operations → verify key exists after SET
```

#### 4d. Twenty CRM Operations

After any GraphQL mutation:
```
1. Verify response contains the created/updated entity
2. Verify no errors in response
3. For deletions → verify entity is gone on a subsequent query
```

---

## Self-Repair Pattern

When validation fails, the agent should try to fix it automatically:

**1. Schema mismatch → correct the types, retry ONCE**
**2. Missing required field → infer from context or ask user**
**3. Connection timeout → retry once with 5s delay**
**4. Wrong UUID → check list first, then retry**

**After self-repair → verify the fix worked.** If not → alert user with exact error.

**Self-repair is a ONE-ATTEMPT only.** If the second attempt fails, stop and report.

---

## Idempotency Principle

Every operation should be safely repeatable:

```
✓ GET (read) — naturally idempotent
✓ POST with unique ID — idempotent (creates once, returns existing)
✗ POST with auto-increment ID — NOT idempotent (creates duplicates)
✗ DELETE — technically idempotent but irreversible (requires confirmation)
```

**When implementing any operation, design it to be idempotent.** If true idempotency is impossible, require user confirmation.

---

## Error-First Logging

When something goes wrong, log the FULL chain:

```
1. What did I try to do?
2. What exactly failed? (full error message, exit code, response body)
3. What was the context? (what preceded the failure)
4. What did I try to recover?
5. What is the recommended next step?
```

**NEVER silently continue after a tool failure.** Every failure must be visible to the user.

---

## Pre-Flight Checklist Template

Use this checklist BEFORE any tool execution:

```markdown
### Pre-Flight Check

- [ ] Within project scope?
- [ ] Within agent permissions?
- [ ] NOT touching GPU?
- [ ] Target reachable/authenticatable?
- [ ] Parameters valid (types, ranges, required)?
- [ ] No dangerous patterns in arguments?
- [ ] Irreversible action confirmed by user?
```

If any box is unchecked → STOP. Resolve the issue before proceeding.

---

## Post-Action Checklist Template

Use this checklist AFTER any significant tool execution:

```markdown
### Post-Action Verification

- [ ] Exit code == 0 (for terminal commands)
- [ ] Response status matches expected (for API calls)
- [ ] Affected rows > 0 (for write operations)
- [ ] Resource status is correct (deployed/running/stopped)
- [ ] No unexpected side effects
- [ ] Dependent operations can proceed safely
```

If any box fails → decide: rollback, alert user, or proceed with caution.

---

## Real-World Examples

### Example 1: Deploying via Coolify (Correct Flow)

```
1. Policy: ✓ Within project scope, ✓ Not GPU, ✓ Has Coolify write access
2. Pre-flight:
   a. Access: GET /api/v1/ping → 200 OK ✓
   b. GPU guard: Not a terminal command → skip ✓
   c. Irreversible: Deploy is risky → show user summary, get confirm ✓
   d. Schema: uuid is valid UUID ✓, all params correct types ✓
3. Execute: POST /api/v1/services/{uuid}/deploy
4. Post-action:
   a. GET /api/v1/services/{uuid} → status = "Running" ✓
   b. Health check: curl http://fqdn/health → 200 OK ✓
5. Report success with details
```

### Example 2: Coolify Deploy (Blocked by Guardrails)

```
1. Policy: ✓ Within project scope, ✓ Not GPU, ✓ Has Coolify write access
2. Pre-flight:
   a. Access: GET /api/v1/ping → 401 Unauthorized ✗
   → STOP. Token expired or wrong. Alert user: "Coolify API returned 401. Check token."
```

### Example 3: GPU Guardrail (Blocked)

```
1. Policy: ✓ Within project scope
2. Pre-flight:
   a. GPU guard: command = "nvidia-smi --query-gpu=memory.used" → GPU-related ✗
   → STOP. "This command accesses GPU. The iron rule prohibits GPU operations."
```

---

## Red Flags — STOP Immediately

If you detect any of these, halt and reassess:

| Signal | Action |
|--------|--------|
| Command contains `nvidia`, `cuda`, `nvcc`, `vram`, `gpu` | BLOCK. GPU rule. |
| Command contains `rm -rf` without explicit file target | BLOCK. Dangerous deletion. |
| Tool call without checking access first | REORDER. Check access before calling. |
| Same operation attempted 2+ times | STOP. Re-analyze. Don't repeat. |
| Unexpected response from API | VERIFY. Check what changed, don't assume. |
| Schema validation failed twice | STOP. Alert user. Don't self-repair blindly. |

---

## Integration with Other Skills

### With `systematic-debugging`
When a tool call fails, switch to systematic-debugging. The post-action verification (Layer 4) failure triggers Phase 1 root cause investigation.

### With `test-driven-development`
Post-action verification is a form of live testing. Run the verification command as the regression test.

### With `plan`
Before executing any plan, run pre-flight checks on every step. If any step fails pre-flight, update the plan.

### With `codebase-review`
When reviewing code, apply schema validation to API contracts, check for GPU access patterns, verify idempotency of operations.

---

## Implementation Guide

To make poka-yoke effective, integrate it into your workflow:

### 1. Every Session Start
Run a quick capability check:
```bash
# Verify infrastructure is reachable
curl -s http://192.168.1.230:8000/api/v1/ping
# Verify MCP connections
twenty list-objects
```
Report status before starting work.

### 2. Before Every Tool Call
Mentally (and visibly to user) check: scope → GPU → access → schema.

### 3. After Every Significant Action
Verify the result. Don't trust the tool's exit code alone — check the actual state.

### 4. For Automated Operations (cron jobs)
- Every cron job MUST have a pre-flight check in its script
- Every cron job MUST have a post-action health-check
- Every cron job MUST log the full chain on failure
- No silent failures allowed

---

## Quick Reference

| Guardrail | When | What | Blocks |
|-----------|------|------|--------|
| **Policy** | Session start | Define permissions | Out-of-scope actions |
| **Access** | Before every tool call | Verify reachability/auth | Silent API failures |
| **GPU** | Every terminal/browser call | Check for GPU patterns | GPU process interference |
| **Schema** | Before every tool call | Validate arguments types | Parameter errors |
| **Irreversible gate** | Before destructive ops | Require user confirm | Accidental deletions |
| **Post-action verify** | After every significant op | Check result state | Silent failures |
| **Self-repair limit** | On validation failure | Max 1 retry | Retry loops |
| **Error-first log** | On any failure | Full chain documentation | Hidden failures |

---

## Real-World Impact

From the research and architecture analysis:
- **Pre-execution validation** catches ~80% of failure modes
- **Post-execution verification** catches the remaining ~20% (API errors, race conditions)
- **GPU guardrail** prevents the most destructive error type
- **Schema validation** eliminates type-parameter mismatches (the #1 API error)
- **Compositional approach** (all layers together) reduces error rate to <0.1%

**The goal is not perfection. The goal is catching errors BEFORE they cause damage.**

---

## References

- Alice Labs: AI Agent Tool Use Patterns (pre-execution / post-execution validation)
- Microsoft Security Blog: Defense in Depth for Autonomous AI Agents (May 2026)
- Medium / Data Science Collective: Stop Trusting Your Agent with Tool Arguments (Feb 2026)
- The Backend Developers: Runtime Verification for AI Agents (May 2026)
- Agno: Guardrails for AI Agents Framework (Oct 2025)
- Toyota Production System: Poka-Yoke / Mistake-Proofing (original concept)
- OWASP: Agentic AI Safety Testing