Development skill + hook

One-way door check

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

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.

How it works

Detect

Hook intercepts file creation

The PreToolUse hook fires on every Write call. It extracts the file path and checks it against known one-way-door filename patterns.

Block

One-way door detected

If the file matches a one-way-door pattern, the hook exits with code 2 (block) and sends a message to stderr explaining what was caught and why.

Ask

Claude discusses trade-offs

Claude uses AskUserQuestion to present the architectural decision: what it does, alternative approaches, and trade-offs. The user decides how to proceed.

Proceed

Write with confidence

After the user makes an informed choice, Claude retries the write. Two-way door files always pass through silently with no interruption.

The hook script

A shell script that runs on every Write tool call. It pattern-matches the filename and blocks with exit code 2 if the file is a one-way door.

#!/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

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

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$|rbac|permissions"; then
    ONE_WAY=1; REASON="auth / security rules"
fi

# ... (8 categories total)

if [ "$ONE_WAY" = "1" ]; then
    echo "ONE_WAY_DOOR: $FILENAME ($REASON)" >&2
    echo "Blocked. Discuss trade-offs first." >&2
    exit 2  # Block the write
fi

exit 0  # Allow two-way doors

Full script with all 8 categories available in the skill directory.

Two-way doors

These file types pass through the hook silently. They're safe to decide quickly and change later.

UI components

Utilities

Test files

Documentation

Styling / CSS

Logging

Static assets

App config

Installation

Option 1: Install the skill

# Clone the repository

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

# Copy the skill to your Claude config

cp -r claude-skills-journalism/one-way-door ~/.claude/skills/

Option 2: Add the CLAUDE.md rule

Add this paragraph to your project's CLAUDE.md for prompt-based enforcement (no hook needed):

### 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 the automated hook

For automated enforcement, save the hook script and add this to your settings.json:

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

Or download just this skill from the GitHub repository.

Related skills

Test-first bugs Vibe coding Security checklist

Measure twice, cut once

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

View on GitHub