Development skill + hook

One-way door check

Updated

Flag irreversible architectural decisions before you commit to them. The most expensive mistakes aren't bugs, they're decisions that can't be undone.

Works in: Uses the open Agent Skills format. Codex: candidate, adapter review pending.

The concept

One-way doors

Decisions that create gravity. Once traffic, users, or other code depends on them, changing course gets expensive.

  • Database schema after launch
  • API contract with external consumers
  • Auth model shaping permissions
  • Infrastructure stack your team learns

Two-way doors

Decisions you can reverse easily. Walk through, and if it's wrong, walk back. No lasting consequences.

  • UI components and styling
  • Utility functions and helpers
  • Test infrastructure
  • Documentation and logging

This skill teaches Claude to recognize the difference and pause before one-way doors. The companion hook automates enforcement by blocking file creation for known architectural patterns until you've discussed the trade-offs.

What gets flagged

Data models

Schemas, migrations, entity definitions. Once your database has rows, every change requires a migration.

Infrastructure

Docker, Terraform, Kubernetes, Helm. Infrastructure choices constrain everything built on top.

Auth boundaries

Security rules, RBAC, permissions. Auth boundaries are load-bearing walls in your architecture.

API contracts

OpenAPI specs, protobuf definitions, route files. Published APIs are promises to consumers.

Event systems

Pub/sub, message queues, event buses. Event schemas are contracts between producers and consumers.

CI/CD pipelines

GitHub Actions, GitLab CI, Jenkins. Pipelines become the backbone of your release process.

Dependencies

package.json, Cargo.toml, go.mod. Framework choices ripple through your entire codebase.

Cloud configs

Firebase, Firestore indexes. Cloud service configs lock you into specific providers and architectures.

Shared decision workflow

Detect

Identify the decision

Check whether a proposed file or change defines a decision that is costly to reverse.

Block

One-way door detected

Pause before making the change. Explain what is difficult to reverse and list viable alternatives.

Ask

Ask for an explicit decision

Ask the user and wait for an explicit answer. Use the client's structured question tool when it has one.

Proceed

Approve, then write with confidence

Proceed only after approval. Record the selected approach and its trade-offs in the project instruction file or decision record. Two-way door files always pass through silently, and a new session starts with a clean slate.

Optional Claude Code enforcement

Two shell scripts that share a session-scoped approval ledger. The check runs on every Write: it pattern-matches the filename and blocks with exit code 2 if the file is a one-way door it hasn't already seen approved this session.

#!/bin/sh
INPUT=$(cat)
[ -z "$INPUT" ] && exit 0

FILE_PATH=$(echo "$INPUT" | grep -oP '"file_path"\s*:\s*"[^"]*"' \
  | head -1 | sed 's/.*"file_path"\s*:\s*"//;s/"//')
[ -z "$FILE_PATH" ] && exit 0

# Session-scoped approval ledger
SESSION_ID=$(echo "$INPUT" | grep -oP '"session_id"\s*:\s*"[^"]*"' \
  | head -1 | sed 's/.*"session_id"\s*:\s*"//;s/"//')
[ -z "$SESSION_ID" ] && SESSION_ID="default"
STATE_DIR="$HOME/.claude/hooks/state/one-way-door"; mkdir -p "$STATE_DIR"
APPROVED_FILE="$STATE_DIR/$SESSION_ID.approved"
PENDING_FILE="$STATE_DIR/$SESSION_ID.pending"

# Already approved this session: note it and allow
if [ -f "$APPROVED_FILE" ] && grep -Fxq "$FILE_PATH" "$APPROVED_FILE"; then
    echo "one-way-door: proceeding with previously-approved $(basename "$FILE_PATH")" >&2
    exit 0
fi

FILENAME=$(basename "$FILE_PATH")
FILENAME_LOWER=$(echo "$FILENAME" | tr "[:upper:]" "[:lower:]")
FILE_PATH_LOWER=$(echo "$FILE_PATH" | tr "[:upper:]" "[:lower:]")
DIR=$(dirname "$FILE_PATH")

# Early-exit safelist: always-reversible classes pass even if the name
# contains a keyword like "auth" (tests, fixtures/mocks, markdown, docs)
if echo "$FILENAME_LOWER" | grep -qE \
  "^test_.*\.py$|_test\.py$|\.test\.(ts|tsx|js|jsx)$|\.spec\.(ts|tsx|js|jsx)$"; then
    exit 0
fi
if echo "$FILE_PATH_LOWER" | grep -qE \
  "/tests?/|/__tests__/|/fixtures?/|/mocks?/|/__mocks__/"; then
    exit 0
fi
if echo "$FILENAME_LOWER" | grep -qE "\.md$"; then exit 0; fi
if echo "$FILENAME_LOWER" | grep -qE "\.txt$|\.rst$"; then
    echo "$DIR" | grep -qE "plans?|docs?|notes?|superpowers" && exit 0
fi

ONE_WAY=0
REASON=""

# Data models, infra, auth, APIs, events, deps, cloud, CI/CD
if echo "$FILENAME_LOWER" | grep -qE \
  "schema\.(prisma|graphql|sql)|migration|\.sql$|models?\.(py|ts|js)$"; then
    ONE_WAY=1; REASON="data model / database schema"
fi

if echo "$FILENAME_LOWER" | grep -qE \
  "^(docker-compose|dockerfile|terraform|pulumi|cdk)|\.tf$"; then
    ONE_WAY=1; REASON="infrastructure config"
fi

if echo "$FILENAME_LOWER" | grep -qE \
  "auth\.(ts|js|py)|\.rules$|security\.(ts|js|py|json|rules|yaml|yml)|rbac\.(ts|js|py|json)|permissions\.(ts|js|py|json)"; then
    ONE_WAY=1; REASON="auth / security rules"
fi

# ... (8 categories total)

if [ "$ONE_WAY" = "1" ]; then
    grep -Fxq "$FILE_PATH" "$PENDING_FILE" 2>/dev/null \
      || printf '%s\n' "$FILE_PATH" >> "$PENDING_FILE"  # record as pending
    echo "ONE_WAY_DOOR: $FILENAME ($REASON)" >&2
    echo "Blocked. Ask the user for an explicit decision, then retry." >&2
    exit 2  # Block the write
fi

exit 0  # Allow two-way doors

A second optional Claude Code hook runs on PostToolUse:AskUserQuestion. When the user answers a structured question, it promotes every pending path to approved so the retried write passes. It never blocks. It keys on the event, not the specific question, so an unrelated question answered while a file is pending approves it too. The block-then-discuss prompt is the guardrail; the ledger stops an already-discussed file from re-blocking.

#!/bin/sh
# one-way-door-approve.sh (PostToolUse:AskUserQuestion)
INPUT=$(cat); [ -z "$INPUT" ] && exit 0

SESSION_ID=$(echo "$INPUT" | grep -oP '"session_id"\s*:\s*"[^"]*"' \
  | head -1 | sed 's/.*"session_id"\s*:\s*"//;s/"//')
[ -z "$SESSION_ID" ] && SESSION_ID="default"
STATE_DIR="$HOME/.claude/hooks/state/one-way-door"; mkdir -p "$STATE_DIR"
APPROVED_FILE="$STATE_DIR/$SESSION_ID.approved"
PENDING_FILE="$STATE_DIR/$SESSION_ID.pending"

[ -s "$PENDING_FILE" ] || exit 0  # nothing pending

# Promote each pending path into approved, deduped
while IFS= read -r path; do
    [ -z "$path" ] && continue
    grep -Fxq "$path" "$APPROVED_FILE" 2>/dev/null \
      || printf '%s\n' "$path" >> "$APPROVED_FILE"
done < "$PENDING_FILE"

: > "$PENDING_FILE"  # clear pending now that it's approved
exit 0

Full check script with all 8 categories, plus the approval hook, in the skill directory.

Two-way doors

These file types pass through the hook silently. They're safe to decide quickly and change later. Test files, Markdown, and docs/plans text files are enforced by an early-exit safelist, so they pass even when the name contains a keyword like "auth".

UI components

Utilities

Test files

Documentation

Styling / CSS

Logging

Static assets

App config

Installation

Option 1: Install the skill

# Recommended: install the dev-toolkit plugin

/plugin marketplace add jamditis/claude-skills-journalism

/plugin install dev-toolkit@claude-skills-journalism

# Or copy just this skill from the plugin tree

git clone https://github.com/jamditis/claude-skills-journalism.git

mkdir -p ~/.claude/skills ~/.agents/skills

cp -r claude-skills-journalism/dev-toolkit/skills/one-way-door ~/.claude/skills/ # Claude Code

cp -r claude-skills-journalism/dev-toolkit/skills/one-way-door ~/.agents/skills/ # Codex

Option 2: Add the project instruction rule

Add this paragraph to the canonical project instruction file for prompt-based enforcement:

### One-way door check
Before creating new files that represent architectural
decisions, ask: "Which of these decisions would be
difficult to reverse?" One-way doors include data models,
service communication patterns, auth boundaries, tenancy
models, and infrastructure configs. If a decision is a
one-way door, pause and discuss the trade-offs before
committing.

Option 3: Add optional Claude Code hooks

For optional Claude Code enforcement, save both scripts and add this to Claude Code settings.json. The shared skill does not depend on these hooks.

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Write",
      "hooks": [{
        "type": "command",
        "command": "/path/to/one-way-door-check.sh"
      }]
    }],
    "PostToolUse": [{
      "matcher": "AskUserQuestion",
      "hooks": [{
        "type": "command",
        "command": "/path/to/one-way-door-approve.sh"
      }]
    }]
  }
}

Windows (PowerShell)

On Windows, hooks run through PowerShell and file paths can use backslashes. Behavior-matched ports, one-way-door-check.ps1 and one-way-door-approve.ps1, ship in the skill directory and use the same session ledger, safelist, and categories. Copy both into your hooks folder (for example %USERPROFILE%\.claude\hooks\), then wire them with the PowerShell launcher, update the paths to match where you saved them (replace <you>):

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Write",
      "hooks": [{
        "type": "command",
        "command": "powershell -ExecutionPolicy Bypass -File C:/Users/<you>/.claude/hooks/one-way-door-check.ps1"
      }]
    }],
    "PostToolUse": [{
      "matcher": "AskUserQuestion",
      "hooks": [{
        "type": "command",
        "command": "powershell -ExecutionPolicy Bypass -File C:/Users/<you>/.claude/hooks/one-way-door-approve.ps1"
      }]
    }]
  }
}

Or browse this skill in the GitHub repository.

Related skills

Measure twice, cut once

Pause before irreversible decisions. A five-minute conversation about trade-offs saves weeks of migration pain.

View on GitHub