/justify

name: justify
description: Audits changes for additive bias and Iron Law compliance. Use when reviewing completed work before merging or after AI-assisted implementation.
alwaysApply: false
category: workflow-methodology
tags:
- justification
- proof-of-work
- anti-additive-bias
- code-review
- iron-law
dependencies:
- imbue:proof-of-work
- leyline:additive-bias-defense
tools: []
usage_patterns:
- post-implementation-review
- pre-commit-audit
- change-justification
complexity: intermediate
estimated_tokens: 2800
role: entrypoint

> The simplest change that fixes the problem is the > safest change to merge. > Adding code is easy. Removing the need for code is > engineering.

Justify

The Additive Bias Problem

AI models are trained to be helpful, which creates a systematic bias toward *adding* code rather than *fixing* root causes:

| AI Default Behavior | Correct Behavior | |---------------------|------------------| | Add a workaround | Fix the root cause | | Modify test expectations | Fix the implementation | | Create a new helper | Use an existing one | | Add error handling | Prevent the error | | Add a compatibility shim | Remove the old code | | Wrap in try/catch | Fix the exception source |

This skill audits changes for these patterns and requires explicit justification for each.

When To Use

• After completing implementation work
• Before committing or creating PRs
• When reviewing your own changes for quality
• When scope-guard flags RED/YELLOW zone

When NOT To Use

• Before writing the code, because this audits work already done (use

`imbue:karpathy-principles`)

• Deciding whether a feature belongs in scope (use `imbue:scope-guard`)

Audit Protocol

Step 1: Gather the Delta

# Determine base branch
base=$(git merge-base master HEAD 2>/dev/null \
  || git merge-base main HEAD 2>/dev/null)

# Get change statistics
git diff "$base" --stat
git diff "$base" --shortstat
git diff "$base" --diff-filter=A --name-only  # new files
git diff "$base" --diff-filter=M --name-only  # modified files
git diff "$base" --diff-filter=D --name-only  # deleted files

Step 2: Compute Additive Bias Score

Score each dimension 0-3 (0 = clean, 3 = high bias):

| Signal | Weight | How to Measure | |--------|--------|----------------| | Line ratio | 2x | `additions / max(deletions, 1)` | | New files | 2x | Count of `--diff-filter=A` | | Test logic changes | 3x | Test assertion/expectation diffs | | New abstractions | 1x | New classes, functions, modules | | Workaround patterns | 2x | Try/catch, if/else guards added |

**Line Ratio Scoring:**

| Ratio | Score | Interpretation | |-------|-------|----------------| | < 2:1 | 0 | Balanced change | | 2:1 to 5:1 | 1 | Mildly additive | | 5:1 to 10:1 | 2 | Additive bias likely | | > 10:1 | 3 | Strong additive bias |

**Aggregate Score:**

bias_score = sum(signal_score * weight) / sum(weights)

| Aggregate | Zone | Action | |-----------|------|--------| | 0.0 - 0.5 | GREEN | Proceed | | 0.5 - 1.5 | YELLOW | Justify each signal | | 1.5 - 2.5 | RED | Rethink approach | | 2.5+ | STOP | Likely wrong approach |

Step 3: Iron Law Compliance Check

The Iron Law states: tests drive implementation, not the other way around. Check for violations:

# Find test files that were modified
git diff "$base" --name-only | rg "test_|_test\.|spec\." \
  || git diff "$base" --name-only | grep -E "test_|_test\.|spec\."

# For each modified test file, check what changed
git diff "$base" -- <test_file> | rg "^[-+].*assert|^[-+].*expect|^[-+].*should"

**Violation patterns (test logic was tampered):**

• Assertion values changed (expected output modified)
• Test cases removed or commented out
• `@skip` or `@pytest.mark.skip` added
• Error expectations weakened (broad exception types)
• Mock return values changed to match new behavior
• Test renamed to no longer describe original behavior

**Each violation requires explicit justification:**

> "I changed this test assertion because the > *requirement* changed, not because my implementation > couldn't meet the original requirement."

If the requirement didn't change, the test should not change. Fix the implementation instead.

Step 4: Minimal Intervention Analysis

For each changed file, answer:

1. **Was this change necessary?** Could the goal be achieved without touching this file?

2. **Was this the minimal change?** Could fewer lines achieve the same result?

3. **Did this change add or remove complexity?** New functions, classes, or control flow = added complexity that needs justification.

4. **Is there a subtraction-first alternative?** Could removing code fix the problem instead of adding code?

Step 4.5: Invariant Impact Analysis

Changes can be minimal and still catastrophically wrong if they silently revise a load-bearing design decision. For each changed file, check whether it touches a design invariant:

**What counts as an invariant:**

• Architectural patterns (module boundaries, layer

separation, data flow direction)

• Data structure choices (why a map vs list, why

normalized vs denormalized)

• API contracts (public interfaces, protocol formats)
• Error handling strategies (fail-fast vs recovery)
• Concurrency models (single-threaded assumption,

actor model, shared-nothing)

**Detection heuristic:**

# Check for structural changes (new modules, moved
# boundaries, changed interfaces)
git diff "$base" --name-only | rg "(interface|abstract|base|core|types|schema|model)" \
  || git diff "$base" --name-only | grep -E "(interface|abstract|base|core|types|schema|model)"

# Check for pattern-breaking changes
git diff "$base" -U5 | rg "(TODO.*refactor|HACK|WORKAROUND|XXX)" \
  || git diff "$base" -U5 | grep -E "(TODO.*refactor|HACK|WORKAROUND|XXX)"

**When an invariant conflict is detected:**

Do NOT silently pick a resolution. Present the three options to the human:

| Option | Description | When Right | |--------|-------