Proof Of Work

"It looks correct" is not "I verified it works."

Proof-of-work is the discipline of closing that gap:

reproducible evidence before any claim that a task is done.

Proof of Work

Table of Contents

• Overview
• The Iron Law
• Usage Standards
• Validation Protocol
• Integration
• Validation Checklist
• Red Flag Self-Check
• Exit Criteria

Overview

The "Proof of Work" methodology prevents premature completion claims by requiring technical verification before stating that a task is finished. For example, instead of assuming an LSP configuration functions after a restart, we verify that the server starts and that tools respond to queries. This approach confirms the solution works before the user attempts validation.

Before claiming completion, provide reproducible evidence of the solution's performance and address edge cases. All claims must be backed by actual command output captured in the current environment.

The Iron Law

NO IMPLEMENTATION WITHOUT A FAILING TEST FIRST NO COMPLETION CLAIM WITHOUT EVIDENCE FIRST NO CODE WITHOUT UNDERSTANDING FIRST

The Iron Law prevents testing from becoming a perfunctory exercise. If an implementation is planned before tests are written, the RED phase fails to drive the design. Understand the technical rationale for an approach and its limitations before declaring it done. Before writing code, document evidence of the failure being addressed and confirm that tests are driving the implementation.

Verification and TDD Workflow

Verify the fundamentals of the implementation and the reasons for choosing it over alternatives. Identify where a solution might fail rather than stating it should always work. The TDD cycle follows these mandatory steps:

1. RED: Write a failing test before implementation. 2. GREEN: Create a minimal implementation that passes the test. 3. REFACTOR: Improve the code without changing its behavior.

Iron Law Self-Check

Iron Law Progress Tracking

• proof:iron-law-red: Failing test written before implementation.
• proof:iron-law-green: Minimal implementation passes test.
• proof:iron-law-refactor: Code improved without behavior change.
• proof:iron-law-coverage: Coverage gates passed (line, branch, and mutation).

Confirm that work passes all line, branch, and mutation coverage gates. For detailed enforcement patterns, see iron-law-enforcement.md.

Usage Standards

Apply this skill before stating that work is "done," "finished," or "ready." Use it before recommending solutions or stating that a configuration "should work." Stop if you find yourself assuming a configuration is correct without testing it or recommending a fix without first reproducing the problem. Red flags include thinking "this looks correct" without actual verification. If you cannot explain each line of a configuration or why a specific practice applies to the current context, the necessary validation steps have been skipped.

Validation Protocol

Step 1: Reproduce the Problem (proof:problem-reproduced)

Before proposing a solution, verify the current state. Use tools like ps, echo, and cat to check running processes, environment variables, and configuration files. Document the failure with command output and error logs.

Step 2: Test the Solution (proof:solution-tested)

Before claiming a solution works, execute it in the current environment. Capture the actual output and confirm that it matches expected behavior. Do not rely on assumed output.

Step 3: Check for Known Issues (proof:edge-cases-checked)

Research known bugs and limitations related to the approach. Check GitHub issues, version compatibility, and official documentation to identify potential blockers or common pitfalls.

Step 4: Capture Evidence (proof:evidence-captured)

Use imbue:proof-of-work to document the commands executed, their output, timestamps, and the conclusions drawn from each step.

Step 5: Prove Completion (proof:completion-proven)

Define acceptance criteria and validate each item. If a blocker is identified, document the diagnosis with evidence and provide workaround options instead of claiming completion.

Integration

With Improvement Workflows

Use proof-of-work to validate improvement opportunities identified by /update-plugins or /fix-workflow. Document the baseline metrics (step count, failure rate, duration), test the proposed changes, and capture the improved metrics to demonstrate quantitative impact.

Validation Checklist (Before Claiming "Done")

Verify that the problem was reproduced with evidence and the solution was tested in the actual environment. Research known issues and consider edge cases. Capture evidence in a reproducible format and confirm that all acceptance criteria are met. The completion statement must detail the specific tests run and their results, citing evidence for each claim.

Red Flag Self-Check

Before sending a completion message, confirm that you have run the recommended commands and captured their output. Verify that you have researched known issues and that the validation steps are reproducible by the user. Ensure you are proving rather than assuming.

Supporting Modules

• TodoWrite naming patterns: naming

conventions and safe deletion rules for imbue TodoWrite items

• Evidence logging: structured

evidence capture, audit trails, and reproducibility patterns

• Independent verification: for

high-stakes changes, why the producing agent may not be its own sole verifier, and what counts as an independent check

Related Skills

• imbue:karpathy-principles: the "Goal-Driven Execution" principle

wraps the Iron Law in a four-principle synthesis useful as a pre-flight gate

• See docs/quality-gates.md#skill-level-quality-gate-composition for

the full gate-skill federation graph

Exit Criteria

Complete all progress tracking items. Create an evidence log with reproducible proofs. Define and validate acceptance criteria, and document any identified blockers.

Acceptance Criteria

Definition of Done (DoD) templates for common completion scenarios.

Based on Agile acceptance criteria best practices.

Core Principles

1. SMART Criteria: Specific, Measurable, Achievable, Relevant, Testable 2. Binary Outcomes: Must be pass/fail, no "partially complete" 3. User-Verifiable: User can independently test each criterion 4. Evidence-Backed: Each criterion links to proof

Template Format

## Task: [Description]

### Acceptance Criteria
- [ ] [Criterion 1 - specific, testable]
- [ ] [Criterion 2 - specific, testable]
- [ ] [Criterion 3 - specific, testable]

### Test Evidence
- Criterion 1: [Evidence reference] → PASS / FAIL
- Criterion 2: [Evidence reference] → PASS / FAIL
- Criterion 3: [Evidence reference] → PASS / FAIL

### Status
- COMPLETE: All criteria passed
- PARTIAL: Some criteria passed (list blockers)
- BLOCKED: Cannot complete (explain why)

### User Verification Steps
1. [Step-by-step instructions for user to verify]
2. [Expected outcome at each step]

---

Common Scenarios

1. Configuration Setup

## Task: Configure LSP for Claude Code

### Acceptance Criteria
- [ ] Language servers installed and in $PATH
- [ ] MCP configuration file contains cclsp entry
- [ ] ENABLE_LSP_TOOL environment variable set to 1
- [ ] cclsp starts without errors when Claude Code launches
- [ ] LSP tools (find_definition, find_references) are callable from Claude

### Test Evidence
- Language servers: [E1] `which pylsp` returns valid path → PASS
- MCP config: [E2] `.mcp.json` contains cclsp entry → PASS
- Env var: [E3] `echo $ENABLE_LSP_TOOL` returns "1" → PASS
- cclsp starts: [E4] `ps aux | grep cclsp` shows running process → FAIL
- LSP tools available: [E5] Cannot test (blocked by E4) → BLOCKED

### Status
BLOCKED - cclsp does not start in Claude Code 2.0.76 due to bug #14803

### Known Issues
- Issue #14803: LSP plugin loading broken in versions 2.0.69-2.0.76
- Source: https://github.com/anthropics/claude-code/issues/14803

### User Verification Steps
Cannot provide verification steps - task is blocked by upstream bug.

**Workaround Options:**
1. Downgrade to Claude Code 2.0.67
2. Wait for fix in future release

---

2. Feature Implementation

## Task: Implement user authentication

### Acceptance Criteria
- [ ] User can register with email/password
- [ ] User can log in with valid credentials
- [ ] User cannot log in with invalid credentials
- [ ] Session persists across page refreshes
- [ ] User can log out and session is cleared
- [ ] Passwords are hashed (not stored in plaintext)
- [ ] All auth endpoints have rate limiting
- [ ] Auth flow has >85% test coverage

### Test Evidence
- Registration: [E1] `curl -X POST /register` returns 201 → PASS
- Valid login: [E2] `curl -X POST /login` with correct creds → PASS
- Invalid login: [E3] `curl -X POST /login` with wrong creds returns 401 → PASS
- Session persistence: [E4] Tested in browser, session survives refresh → PASS
- Logout: [E5] Session cleared after `/logout` → PASS
- Password hashing: [E6] DB query shows bcrypt hash, not plaintext → PASS
- Rate limiting: [E7] 6th request within 1min returns 429 → PASS
- Test coverage: [E8] `pytest --cov` shows 87% for auth module → PASS

### Status
COMPLETE - All criteria passed

### User Verification Steps
1. Run test suite: `pytest tests/test_auth.py -v`
2. Expected: All tests pass (8/8)
3. Start dev server: `npm run dev`
4. Visit `/register`, create account
5. Expected: Redirected to dashboard
6. Refresh page
7. Expected: Still logged in
8. Click logout
9. Expected: Redirected to login page

---

3. Bug Fix

## Task: Fix memory leak in connection pool

### Acceptance Criteria
- [ ] Memory leak reproduced and characterized
- [ ] Root cause identified and documented
- [ ] Fix implemented and tested
- [ ] Memory usage stable over 1000 operations
- [ ] No regression in connection pool performance
- [ ] Unit test added to prevent regression

### Test Evidence
- Leak reproduced: [E1] `valgrind` shows 4KB unreleased per connection → CONFIRMED
- Root cause: [E2] Code review shows missing `pool.release()` in error path → IDENTIFIED
- Fix implemented: [E3] Added `finally` block with `pool.release()` → DONE
- Memory stable: [E4] 1000 ops, memory growth <1% → PASS
- No regression: [E5] Benchmark shows same throughput (±2%) → PASS
- Regression test: [E6] Added `test_connection_cleanup_on_error()` → PASS

### Status
COMPLETE - All criteria passed

### User Verification Steps
1. Run regression test: `pytest tests/test_connection_pool.py::test_connection_cleanup_on_error`
2. Expected: Test passes
3. Run memory profiling: `python -m memory_profiler scripts/stress_test_pool.py`
4. Expected: Memory usage stays flat over 1000 operations

---

4. Documentation Update

## Task: Document new API endpoint

### Acceptance Criteria
- [ ] Endpoint description includes purpose and use cases
- [ ] Request format documented with example
- [ ] Response format documented with example (success and error)
- [ ] Authentication requirements specified
- [ ] Rate limits documented
- [ ] Common error codes listed with explanations
- [ ] Code example provided in at least 2 languages
- [ ] Documentation tested by someone unfamiliar with the feature

### Test Evidence
- Description: [E1] README.md contains "## POST /api/users" section → PASS
- Request format: [E2] JSON schema and curl example provided → PASS
- Response format: [E3] Both 200 and 400 responses documented → PASS
- Auth requirements: [E4] "Requires Bearer token" documented → PASS
- Rate limits: [E5] "100 requests/hour" documented → PASS
- Error codes: [E6] Table of 400, 401, 429, 500 with explanations → PASS
- Code examples: [E7] Python and JavaScript examples provided → PASS
- Testing: [E8] Junior dev followed docs successfully → PASS

### Status
COMPLETE - All criteria passed

### User Verification Steps
1. Open `docs/API.md`
2. Find "POST /api/users" section
3. Copy the curl example
4. Run it with your API key
5. Expected: Receives documented response format
6. Try with invalid data
7. Expected: Receives documented error response

---

5. Research/Investigation

## Task: Research best LSP setup for Claude Code

### Acceptance Criteria
- [ ] Evaluated at least 3 different LSP integration approaches
- [ ] Each approach tested in actual Claude Code environment
- [ ] Pros/cons documented for each approach
- [ ] Known issues/bugs researched for each approach
- [ ] Recommendation provided with evidence
- [ ] Reproduction steps documented for recommended approach

### Test Evidence
- Approach 1 (native LSP): [E1] Tested in 2.0.76 → FAIL (bug #14803)
- Approach 2 (cclsp MCP): [E2] Config tested, cclsp starts → PARTIAL (tools not exposed)
- Approach 3 (downgrade to 2.0.67): [E3] Research shows this version works → VIABLE
- Pros/cons: [E4] Comparison table created → DONE
- Known issues: [E5] GitHub search completed, issues documented → DONE
- Recommendation: [E6] "Downgrade to 2.0.67 until bug fixed" → PROVIDED
- Reproduction steps: [E7] Step-by-step downgrade instructions → DOCUMENTED

### Status
COMPLETE - Research concluded with recommendation

### Findings Summary
- Native LSP broken in 2.0.76 (blocker)
- cclsp MCP configured but tools unavailable (blocker)
- Downgrade to 2.0.67 is only working solution currently

### User Verification Steps
1. Follow documented downgrade steps
2. Verify LSP tools become available in 2.0.67
3. Expected: `mcp__cclsp__find_definition` and similar tools work

---

Anti-Patterns (What NOT to Do)

Vague Criteria

Bad:

• [ ] LSP is set up correctly

Good:

• [ ] ps aux | grep cclsp shows running process
• [ ] echo $ENABLE_LSP_TOOL returns "1"

Non-Testable Criteria

Bad:

• [ ] Code looks good

Good:

• [ ] ruff check passes with 0 errors
• [ ] pytest --cov shows >85% coverage

Assumed Rather Than Proven

Bad:

• Status: COMPLETE - Should work after restart

Good:

• Status: PARTIAL - Restart required, tested in fresh session [E9]

Missing Evidence Links

Bad:

• Session persistence: PASS

Good:

• Session persistence: [E4] Browser test shows cookie survives refresh → PASS

---

Completion Checklist

Before claiming "done", verify:

• [ ] Every acceptance criterion is SMART (specific, measurable, achievable, relevant, testable)
• [ ] Every criterion has linked evidence
• [ ] Evidence is reproducible (commands/steps provided)
• [ ] User can independently verify each criterion
• [ ] Any blockers are clearly documented
• [ ] Status is accurate (COMPLETE/PARTIAL/BLOCKED)
• [ ] If PARTIAL or BLOCKED, next steps are provided

Anti-Cargo-Cult Reasoning

Prevents superficial technical artifacts created through copy-paste methodology and blind AI delegation. This module provides understanding verification protocols used across imbue skills.

The Cargo Cult Problem

Definition: Cargo cult programming is the ritual inclusion of code, patterns, or practices that serve no understood purpose: code that "looks right" but nobody can explain WHY it works.

AI Amplification: AI-generated code is syntactically correct, follows best practices, and comes with confident explanations. This makes cargo cult coding faster and far more convincing than ever before. Studies show up to 48% of AI-generated code snippets contain exploitable vulnerabilities from unexamined adoption.

Core Insight: "If you don't understand the code, you'll have no clue how to debug it if something goes wrong."

Understanding Verification Protocol

Before accepting ANY implementation (AI-generated or copied), apply this protocol:

The Five Whys of Understanding

Understanding Checklist

Before claiming understanding of any code:

## Understanding Verification

- [ ] Can explain WHY each line exists (not just WHAT it does)
- [ ] Can predict what happens if key lines are removed
- [ ] Can describe failure modes and edge cases
- [ ] Can explain trade-offs vs. alternative approaches
- [ ] Can modify the code without copy-pasting more examples

Cargo Cult Red Flags

Code-Level Red Flags

Thought-Level Red Flags

AI-Specific Red Flags

Integration Points

With proof-of-work

Understanding before claiming completion:

## Proof-of-Work + Understanding Verification

Before marking `proof:completion-proven`:
- [ ] Can explain implementation without referencing source
- [ ] Have tested by intentionally breaking it
- [ ] Can predict failure modes
- [ ] Have documented WHY not just WHAT

With scope-guard

Understanding as complexity cost:

When scoring Worthiness, INCREASE Complexity score if:

• Solution was copied without modification
• Cannot explain why specific approach was chosen
• Adding technology/pattern you haven't used before
• Solution complexity exceeds problem complexity

Rule: "If you can't teach it, you don't understand it. If you don't understand it, don't ship it."

With rigorous-reasoning

Cargo cult reasoning patterns to catch:

With iron-law-enforcement

Cargo cult TDD anti-patterns:

Recovery Protocol

When cargo cult code is detected:

Step 1: Acknowledge the Gap

## Understanding Gap Acknowledged

I included [code/pattern/practice] without sufficient understanding.

### What I Know
- [List concrete understanding]

### What I Don't Know
- [List gaps - be specific]

### Risk Assessment
- Probability of hidden bugs: [Low/Medium/High]
- Debugging difficulty if issues arise: [Low/Medium/High]

Step 2: Fill the Gap or Remove

Option A: Learn it 1. Read official documentation (not blog posts) 2. Build a minimal spike to understand behavior 3. Apply Five Whys until you can teach it

Option B: Remove it 1. Delete the cargo cult code 2. Find simpler solution you understand 3. Document why the "advanced" solution was rejected

Step 3: Prevent Recurrence

Add to personal/project checklist:

• "I will not copy code I cannot explain"
• "AI suggestions require the same review as junior dev code"
• "Complexity I don't understand is a liability, not an asset"

Evidence Format

When documenting understanding verification:

[U1] Understanding Claim: [What you're claiming to understand]
     Five Whys Applied:
       - Why this approach? [Answer]
       - Why not X alternative? [Answer]
       - What breaks if changed? [Answer]
     Verification Method: [How you tested understanding]
     Confidence: [High/Medium/Low]
     Gaps Acknowledged: [Any remaining uncertainty]

The Fundamental Rule

"If you don't understand the code, don't ship it."

This applies equally to:

• AI-generated code
• Stack Overflow snippets
• Tutorial code
• "Best practice" boilerplate
• Legacy code you inherited

Understanding is not optional. It's the difference between engineering and ritual.

Sources

This module synthesizes research from:

• Wikipedia: Cargo cult programming
• NDepend Blog: Programming by Coincidence
• Medium: AI Creating New Breed of Cargo Cult Programmers
• ACM: Software Reuse in the Generative AI Era
• Addy Osmani: First Principles for Software Engineers
• Codurance: TDD Anti-Patterns

Evidence Logging

Foundation for all evidence-based review workflows. Provides structured evidence capture, audit trails, and reproducibility for analyses.

When To Use

• During any review or analysis workflow to capture reproducible evidence.
• When findings must be traceable to specific commands, outputs, or sources.
• Before finalizing recommendations that stakeholders will act upon.

Activation Patterns

Trigger Keywords: evidence, proof, trace, audit, reproducible, citation, source, verify Contextual Cues:

• "show your work" or "provide evidence"
• "how can I verify this" or "reproduce these findings"
• "cite your sources" or "where did this come from"
• "create an audit trail"
• "document the steps taken"

Step 1: Initialize Log

• Create evidence structure with timestamp and context:
• Session ID or review identifier.
• Repository, branch, and commit hash.
• Analyst identity and review scope.
• Establish naming convention for evidence references (e.g., [E1], [E2]).

Step 2: Capture Commands

• Log every command that produces evidence:

  [E1] Command: git diff --stat HEAD~5..HEAD
       Output: 15 files changed, 234 insertions(+), 89 deletions(-)
       Timestamp: 2024-01-15T10:30:00Z

• Include full command with arguments (no aliases).
• Capture relevant output snippets, not entire dumps.
• Note working directory and environment if relevant.

Step 3: Record Citations

• Log external sources consulted:

  [C1] Source: https://doc.rust-lang.org/nomicon/
       Section: "Working with Unsafe"
       Relevance: Validates unsafe block justification

• Include web searches performed and key results.
• Reference documentation versions (API docs, RFCs, specs).
• Note any AI-assisted analysis with model/prompt context.

Step 4: Index Artifacts

• Catalog generated artifacts:
• Screenshots, diagrams, or visualizations.
• Exported reports or coverage summaries.
• Saved query results or API responses.
• Provide file paths or inline content for small artifacts.
• Note artifact retention policy (ephemeral vs. archived).

Evidence Reference Format

Use consistent format in findings:

Finding: Memory leak in connection pool [E3, C2]
- Evidence [E3]: valgrind output showing 4KB unreleased
- Citation [C2]: PostgreSQL docs on connection lifecycle

Exit Criteria

• All findings traceable to specific evidence references.
• Downstream reports can cite evidence without re-running commands.

Independent Verification

For high-stakes changes, the agent that produced the work may not be its sole verifier. A second, independent check is required.

Why Self-Verification Is Not Enough

Automation-bias research is blunt about the failure mode: correct decision support cut clinician errors by roughly 40%, but incorrect support raised them by 25-33% and reduced independent verification at the same time (medicine, e-prescribing studies). Trust silently collapses verification precisely when the aid is wrong. An agent reviewing its own output inherits the same blind spot that produced the error: it is anchored to its own framing and most confident exactly where it is most mistaken.

Iterative self-refinement does not rescue this. Critical vulnerabilities rose 37.6% after five rounds of LLM self-refinement (Shukla et al. 2025): asking the same model to check its own work again can degrade it, not improve it.

High-stakes domains all forbid sole self-verification for consequential steps: nuclear procedures require a separate qualified individual to confirm critical actions (independent verification, distinct from self-checking); finance separates the maker from the checker (the four-eyes principle). The rule transfers directly.

The Rule

For a change classified high-stakes (see leyline:risk-classification RED or CRITICAL, or any change to auth, migrations, money handling, concurrency, or destructive operations), the producing agent must not be the only thing that verifies it. Require at least one independent check:

• a second agent or model that did not see the first one's

reasoning, evaluating against the requirement rather than the diff's narrative;

• a separate automated gate the producer did not write or tune

(independent test suite, static analysis, fuzzing); or

• a human reviewer.

The verifier evaluates against the original requirement, not against the producer's explanation of what it did. Being handed the producer's narrative re-anchors the second check to the first one's blind spot, which is the thing independent verification exists to break.

What Counts as Independent

Progress Tracking

• proof:independent-verified: a second independent actor

confirmed the high-stakes change against the requirement.

Record who or what performed the independent check and what they evaluated against, as part of the evidence log. For the four-eyes audit trail (which prompt, which agent, which diff, who approved and why), see leyline:usage-logging.

When This Does Not Apply

Low-stakes, reversible changes do not need a second verifier; proof-of-work evidence from the producer is sufficient. Reserve independent verification for the changes where being wrong is expensive or hard to undo. Applying it everywhere turns it into ceremony and trains reviewers to rubber-stamp, which is the exact degradation it exists to prevent.

Iron Law Enforcement

The Iron Law

NO SKILL WITHOUT A FAILING TEST FIRST
NO IMPLEMENTATION WITHOUT A FAILING TEST FIRST
NO COMPLETION CLAIM WITHOUT EVIDENCE FIRST
NO CODE WITHOUT UNDERSTANDING FIRST

This is the fundamental principle that unites TDD (Test-Driven Development) and BDD (Behavior-Driven Development) with proof-of-work and skill authoring. It prevents the Cargo Cult TDD anti-pattern where tests are written to validate pre-conceived implementations rather than to discover the right implementation.

TDD and BDD: Complementary Practices

Both are required. TDD ensures tests come first; BDD ensures tests describe behavior, not implementation details.

The Fourth Law: Understanding Before Code

The fourth principle addresses cargo cult programming - the ritual inclusion of code that "looks right" but nobody can explain. Studies show up to 48% of AI-generated code contains vulnerabilities from unexamined adoption.

Understanding Verification Questions:

• Can I explain WHY this code exists, not just WHAT it does?
• What would break if I removed this line?
• Why this approach over simpler alternatives?
• When would this fail?

See anti-cargo-cult.md for the full protocol.

Why This Matters (The Reddit Insight)

Classic TDD works because humans "feel their way through uncertainty":

"I think I want this behaviour... let me code just that & see if it goes green"

"Oh, that test is awkward to write... maybe my API is wrong"

"This failure is telling me something about my design choices"

When AI pre-plans implementation before writing tests, the RED phase becomes theater. The Iron Law prevents this by requiring documented evidence of failure before any intervention.

Enforcement Levels

Level 1: Self-Enforcement (Default)

Claude recognizes Iron Law violations in its own thought process.

Red Flags That Trigger Self-Enforcement:

Self-Check Protocol:

## Iron Law Self-Check

Before writing ANY code:
1. [ ] Do I have documented evidence of a failure/need?
2. [ ] Am I about to write a test that validates a pre-conceived implementation?
3. [ ] Am I feeling uncertainty about the design? (Good - that's what tests are for)
4. [ ] Have I let the test drive the implementation, or vice versa?
5. [ ] Can I explain WHY this approach, not just WHAT it does?

If I answered "no" to #1, #3, or #5, or "yes" to #2 or #4: STOP AND RESET.

Execution Markdown = Code

Note: L1/L2/L3 below refer to content assertion depth per leyline:testing-quality-standards, distinct from this document's Enforcement Levels 1-5.

Markdown files under skills/, agents/, modules/, and commands/ directories are execution markdown. Claude interprets them as behavioral instructions. They require content assertions following the L1/L2/L3 taxonomy defined in leyline:testing-quality-standards/modules/content-assertion-levels.md.

Iron Law applied to execution markdown:

• L1 assertions (keyword presence) are the minimum for any skill or module change
• L2 assertions (code example validity) are required when the file contains JSON, YAML, or code blocks that Claude will copy as templates
• L3 assertions (behavioral contracts) are required when the file defines decision frameworks, version gates, or behavioral guidance that affects user outcomes

The Documentation Exception case study demonstrated that 37 BDD tests were needed for a single skill's content. Content assertion levels provide the framework for knowing WHICH tests to write, not just that tests are needed.

BDD Test Structure Requirement

All tests MUST follow BDD structure:

class TestFeatureName:
    """
    Feature: [Clear feature description]

    As a [stakeholder]
    I want [feature capability]
    So that [benefit/value]
    """

    @pytest.mark.unit
    def test_scenario_with_clear_outcome(self):
        """
        Scenario: [Clear scenario description]
        Given [initial context]
        When [action occurs]
        Then [expected outcome]
        """
        # Arrange (Given)
        # Act (When)
        # Assert (Then)

BDD Enforcement Checklist:

• [ ] Test class has Feature docstring (As a/I want/So that)
• [ ] Test method has Scenario docstring (Given/When/Then)
• [ ] Test describes BEHAVIOR not implementation
• [ ] Test name reflects the scenario, not the method being tested

---

Cargo Cult TDD Anti-Patterns

Testing theater - tests that look right but don't actually verify behavior:

The "AI Wrote My Tests" Problem:

AI-generated tests are particularly prone to cargo cult patterns:

• Tests validate the AI's implementation, not desired behavior
• Tests pass but don't catch intentional mutations
• Tests look thorough but miss edge cases
• Tests mock so much they test mocks, not code

Prevention: Apply mutation testing. If tests don't fail when code is intentionally broken, they're cargo cult tests.

---

Level 2: Adversarial Verification (Subagent Pattern)

Based on successful community patterns, use adversarial agents to verify Iron Law compliance.

The RED-GREEN-REFACTOR Subagent Pattern:

# Agent 1: RED Agent (Test Author)
role: Write ONLY failing tests
constraints:
  - Cannot see implementation plans
  - Cannot write implementation code
  - Must document WHAT should happen, not HOW
input: Given-When-Then requirement
output: Failing test + failure evidence

# Agent 2: GREEN Agent (Implementer)
role: Write MINIMAL code to pass tests
constraints:
  - Can ONLY see failing tests, not requirements
  - Must write minimum code to go green
  - Cannot add "nice to have" features
input: Failing test
output: Minimal passing implementation

# Agent 3: REFACTOR Agent (Code Improver)
role: Improve code quality WITHOUT changing behavior
constraints:
  - Cannot add new functionality
  - All tests must remain green
  - Focus on readability, not features
input: Passing implementation + tests
output: Refactored code + green tests

Adversarial Verification Rule:

"For every automated thing you ask an LLM to do, create an equal and opposite agent to verify that it did it."

---

Level 3: Git History Analysis (Post-Hoc Verification)

Analyze git history to detect Iron Law violations.

TDD-Compliant Commit Pattern:

commit 1: RED - Add failing test for [feature]
commit 2: GREEN - Implement [feature] to pass test
commit 3: REFACTOR - Clean up [feature] implementation

Violation Detection Signals:

Git History Audit Command:

# Check if TDD was followed for recent commits
git log --oneline -10 | while read sha msg; do
  files=$(git show --name-only --format="" $sha)
  has_test=$(echo "$files" | grep -E "test_|_test\.|\.spec\." || true)
  has_impl=$(echo "$files" | grep -vE "test_|_test\.|\.spec\." || true)

  if [ -n "$has_impl" ] && [ -z "$has_test" ]; then
    echo "WARNING: $sha may violate Iron Law (implementation without test)"
  fi
done

---

Level 4: Pre-Commit Hook Enforcement

Enforce Iron Law at commit time.

Pre-Commit Hook Pattern:

#!/usr/bin/env bash
# .git/hooks/pre-commit - Iron Law Enforcement

# Check if this is an implementation commit
impl_files=$(git diff --cached --name-only | grep -vE "test_|_test\.|\.spec\." | grep -E "\.(py|js|ts|rs|go)$")
test_files=$(git diff --cached --name-only | grep -E "test_|_test\.|\.spec\.")

if [ -n "$impl_files" ] && [ -z "$test_files" ]; then
    echo "IRON LAW VIOLATION: Implementation changes without test changes"
    echo ""
    echo "Implementation files:"
    echo "$impl_files"
    echo ""
    echo "Options:"
    echo "1. Add tests for these changes"
    echo "2. Use 'git commit --allow-empty -m \"RED: failing test for...\"' first"
    echo "3. Set IRON_LAW_SKIP=1 to bypass (NOT RECOMMENDED)"

    if [ "${IRON_LAW_SKIP:-0}" != "1" ]; then
        exit 1
    fi
fi

# If we have tests, verify they fail first (mutation testing light)
if [ -n "$test_files" ]; then
    echo "Verifying tests are meaningful (not assert(true))..."

    # Check for suspicious test patterns
    for file in $test_files; do
        if git show ":$file" | grep -qE "assert.*True|assert.*1.*==.*1|expect.*toBe.*true"; then
            echo "WARNING: $file may contain trivial assertions"
        fi
    done
fi

exit 0

---

Pillar 3 Implementation: Automated Mutation Testing

Status: IMPLEMENTED via .github/workflows/mutation-testing.yml

Mutation testing (Pillar 3 of the Iron Law) is now enforced through a GitHub Actions workflow that runs weekly and on-demand via workflow_dispatch. It uses mutmut to mutate Python source files in each plugin's scripts/ directory and reports mutation scores in the GitHub Actions step summary. To run manually, trigger the "Mutation Testing (Iron Law Pillar 3)" workflow from the Actions tab and select a plugin (or "all").

---

Level 5: Coverage Gate Enforcement

Require evidence of test quality, not just test existence.

Three-Pillar Coverage:

## Coverage Requirements (Iron Law Compliant)

### 1. Line Coverage
- Minimum: 80%
- Measures: Which lines were executed
- Limitation: Can be gamed with trivial tests

### 2. Branch Coverage
- Minimum: 70%
- Measures: Which decision paths were taken
- Limitation: Doesn't prove behavior correctness

### 3. Mutation Coverage
- Minimum: 60%
- Measures: Whether tests catch deliberate bugs
- This is the TRUE test of test quality

**Why Mutation Testing Matters:**

A test that passes when the code is WRONG is worthless.
Mutation testing introduces bugs and checks if tests fail.

Example:

Original code

def is_adult(age): return age >= 18

Mutation 1: Change >= to >

def is_adult(age): return age > 18

If tests still pass, they don't actually test boundary!

Coverage Verification Protocol:

# Before claiming implementation complete:

# 1. Line + Branch coverage
pytest --cov=src --cov-branch --cov-fail-under=80

# 2. Mutation coverage (if mutmut/pytest-mutate available)
mutmut run --paths-to-mutate src/
mutmut results

# Evidence format:
# [E-COV1] Line coverage: 87% (target: 80%) - PASS
# [E-COV2] Branch coverage: 73% (target: 70%) - PASS
# [E-COV3] Mutation score: 65% (target: 60%) - PASS

---

Integration with Proof-of-Work

The Iron Law enforcement extends proof-of-work with TDD-specific validation:

Extended TodoWrite Items

## Iron Law TodoWrite Items

- `proof:iron-law-red` - Failing test written BEFORE implementation
- `proof:iron-law-green` - Minimal implementation passes test
- `proof:iron-law-refactor` - Code improved without behavior change
- `proof:iron-law-coverage` - Coverage gates passed (line/branch/mutation)
- `proof:iron-law-git-audit` - Git history shows TDD compliance

Completion Claim Format (Iron Law Enhanced)

## Implementation Complete: [Feature Name]

### Iron Law Compliance
- [E-TDD1] RED: Failing test committed at <sha> - [Link to commit]
- [E-TDD2] GREEN: Implementation committed at <sha> - [Link to commit]
- [E-TDD3] REFACTOR: Cleanup committed at <sha> - [Link to commit]

### Coverage Evidence
- [E-COV1] Line: 87% (target: 80%) - PASS
- [E-COV2] Branch: 73% (target: 70%) - PASS
- [E-COV3] Mutation: 65% (target: 60%) - PASS

### Acceptance Criteria
- [E1] Feature works as specified - [Test output]
- [E2] Edge cases handled - [Test output]
- [E3] No regressions - [Test suite output]

### Status
COMPLETE - Iron Law compliant, all coverage gates passed

---

Recovery from Violations

If Iron Law was violated (implementation before test):

Option 1: Delete and Redo (Preferred)

# Undo the implementation commit
git reset --soft HEAD~1

# Start over with RED phase
# Write failing test first, commit
# Then write implementation, commit

Option 2: Retrofit with Acknowledgment

## Iron Law Violation Acknowledgment

I violated the Iron Law by writing implementation before tests.

### Evidence of Violation
- Implementation commit: <sha>
- Test commit: <sha> (AFTER implementation)

### Why This Happened
[Explain the rationalization that led to violation]

### Mitigation
- Added the missing tests after the fact (positive, negative, and edge cases)
- Coverage gates still passed: [evidence]
- Tests are behavior-driven, not implementation-driven: [evidence]

### Prevention
[What configuration change prevents this in future?]

---

Case Study: The "Documentation Exception" Violation (2025-01-15)

Context: Creating a new skill (rigorous-reasoning) for anti-sycophancy reasoning.

Violation: Created 8 markdown files (SKILL.md and 7 modules) and updated README/hook without writing any tests first.

Rationalization Chain: 1. "Skills are documentation, not code" → FALSE (skills have testable structure) 2. "The hook test proves it works" → FALSE (only tested JSON serialization) 3. "The user wanted it fast" → RATIONALIZATION (speed ≠ quality waiver)

Detection: User invoked /fix-workflow asking about Iron Law compliance.

Remediation: 1. Wrote 37 BDD-style tests covering:

• Skill existence and structure (6 tests)
• Module existence and content (14 parametrized tests)
• Hook integration (3 tests)
• Required sections and patterns (14 tests)

2. Found and fixed one test (spec mismatch: "polite" vs "politeness") 3. All 37 tests passed

Lessons Learned:

• Markdown files have testable structure (existence, sections, patterns)
• "ls -la shows files exist" is NOT functional verification
• Tests for skills should verify: existence, required content, module links, hook integration

Prevention Added:

• New red flags in self-enforcement table: "It's just documentation/config"
• New section in red-flags.md: "The Documentation Exception Family"
• This case study as documentation

---

Self-Improvement Protocol

Based on community best practices:

"Any time it gets done and it hasn't met the coverage requirements, I ask it how that was possible if it was following TDD? It'll give me a reason... then I'll ask it to adjust its configurations to prevent that from happening in the future."

After Iron Law Violation:

1. Identify: How did the violation happen? 2. Understand: What rationalization allowed it? 3. Configure: What rule/hook prevents it next time? 4. Test: Verify the new rule catches future violations

Configuration Evolution Example:

## Iron Law Configuration History

### v1: Basic self-enforcement
- Relied on Claude checking itself
- FAILURE: Claude rationalized "quick fix" exceptions

### v2: Added pre-commit hook
- Blocks implementation-only commits
- FAILURE: Claude committed test+impl together

### v3: Added git history audit
- Verifies test commits precede implementation
- FAILURE: Claude wrote trivial tests

### v4: Added mutation testing
- Verifies tests actually catch bugs
- CURRENT: Working well, 95% compliance

---

Summary

The Iron Law is a system of enforcement, not only a principle:

1. Self-Enforcement: Red flags table, self-check protocol 2. Adversarial Verification: RED/GREEN/REFACTOR subagents 3. Git History Analysis: Post-hoc verification of TDD compliance 4. Pre-Commit Hooks: Prevent violations at commit time 5. Coverage Gates: Ensure test quality, not just existence 6. Self-Improvement: Learn from violations, strengthen rules

The goal: Make it easier to follow the Iron Law than to violate it.

Output Contracts

An output contract specifies what an agent MUST produce before its work is accepted. Every contract is a YAML block embedded in the agent's dispatch prompt. The contract validator (FR-006) checks compliance on the agent's findings file.

Schema

output_contract:
  # Sections the findings file MUST contain
  required_sections:
    - summary           # Brief overview of findings
    - detailed_findings # Full analysis with evidence
    - evidence          # Evidence log with [E1] tags

  # Minimum number of [EN] evidence citations
  min_evidence_count: 3

  # Files the agent MUST create (relative to workspace)
  expected_artifacts:
    - .coordination/agents/{agent-name}.findings.md

  # Maximum retries before escalating failure
  retry_budget: 2

  # Severity: how strictly the validator enforces
  # strict = reject any missing element
  # normal = reject missing sections + zero evidence
  # lenient = warn but accept (for exploratory work)
  strictness: normal

Field Reference

Contract Templates

Code Review Contract

output_contract:
  required_sections:
    - summary
    - critical_issues
    - warnings
    - suggestions
    - evidence
  min_evidence_count: 5
  expected_artifacts:
    - .coordination/agents/reviewer.findings.md
  retry_budget: 2
  strictness: normal

Audit Contract

output_contract:
  required_sections:
    - summary
    - scope_analyzed
    - findings_by_severity
    - recommendations
    - evidence
  min_evidence_count: 8
  expected_artifacts:
    - .coordination/agents/auditor.findings.md
  retry_budget: 1
  strictness: strict

Research Contract

output_contract:
  required_sections:
    - summary
    - sources_consulted
    - key_findings
    - recommendations
  min_evidence_count: 3
  expected_artifacts: []
  retry_budget: 2
  strictness: lenient

Embedding in Dispatch Prompts

Include the contract block at the END of the agent's dispatch prompt, after the task description:

## Your Task

[task description here]

## Output Contract

Your findings MUST follow this contract.
The validator will reject non-compliant output.

required_sections: summary, detailed_findings, evidence
min_evidence_count: 5
strictness: normal

Write your findings to:
  .coordination/agents/{your-name}.findings.md

Format each evidence citation as:
  [E1] Command: <command run>
       Output: <relevant output snippet>

If the validator rejects your output, you will receive
specific feedback about what is missing and get
{retry_budget} retry attempts.

Validation Rules

The contract validator checks these rules in order:

1. Section check: Each required_sections entry must appear as a Markdown heading (## or ###) in the findings file. Case-insensitive, underscores treated as spaces.

2. Evidence count: Count occurrences of the pattern \[E\d+\] in the findings file. Must be >= min_evidence_count.

3. Artifact check: Each path in expected_artifacts must exist on disk.

4. Zero-evidence gate: If evidence count is 0, the output is ALWAYS rejected regardless of strictness level.

Retry Protocol

When validation fails:

1. Validator produces a specific failure message listing every missing element. 2. Failure message is prepended to a retry prompt that includes the original task. 3. Agent retries with the specific feedback. 4. Retry count is tracked against retry_budget. 5. If budget exhausted, failure is escalated to the parent with the validation detail.

Integration Points

• imbue:proof-of-work: Contracts extend the

existing [E1]/[E2] evidence tag convention.

• imbue:structured-output: Findings file format

aligns with structured deliverable templates.

• plan-before-large-dispatch: The dispatch plan

table includes an "Output Contract" column.

Red Flags - Common Violations

Thought patterns that indicate you're about to violate proof-of-work discipline.

The "Should Work" Family

These flags share a common pattern: substituting assumptions for evidence.

Example recovery ("This should work"):

Let me verify this configuration works:

[Evidence E1] Testing cclsp startup:
$ CCLSP_CONFIG_PATH=config.json npx cclsp@latest
Error: <actual error message>

Result: FAIL - Discovered issue - config path not recognized

The "Installation" Family

Installed does not mean functional.

Example recovery ("X is installed"):

Verifying pylsp installation:

[E1] Binary exists: $ ls -la /usr/local/bin/pylsp - PASS
[E2] Responds: $ pylsp --help - PASS
[E3] Version: $ pylsp --version - PASS (v1.9.0)
[E4] Smoke test: $ echo 'print("test")' | pylsp stdin - PASS

Conclusion: pylsp is installed AND functional.

The "Configuration" Family

Valid syntax does not mean correct semantics.

The "Research" Family

Documentation describes intent, not current reality.

Example recovery ("According to the docs..."):

Documentation verification:

[E1] Docs state: "LSP tools available in Claude Code 2.0.74+"
[E2] Version check: $ claude --version - Result: 2.0.76
[E3] Known issues: Issue #14803 - LSP broken in 2.0.69-2.0.76
[E4] Changelog: No fix mentioned in 2.0.76

Conclusion: Docs correct but current version has regression.

The "Completion" Family

Code written does not mean code working.

Example recovery ("The setup is complete"):

Setup validation:

[E1] Components: pylsp PASS, cclsp PASS, MCP config PASS
[E2] Integration: cclsp starts PASS, servers connect PARTIAL,
     LSP tools FAIL
[E3] Blocker: Issue #14803 - LSP broken in 2.0.76

Status: BLOCKED - Setup complete but unusable due to upstream bug
Next steps: Downgrade to 2.0.67 OR wait for fix

The "Documentation Exception" Family

Markdown files and config files have testable structure.

The Cargo Cult Family

Using code or patterns you cannot explain.

Self-Monitoring Questions

Before ANY completion claim, ask yourself:

1. "Did I run the actual command?" Not "it should work if you run X" but "I ran X and here's the output."

2. "Did I test in the target environment?" Not "works on my machine" but "tested in user's environment."

3. "Did I research known issues?" Not "according to docs" but "docs say X, BUT issue #123 shows Y."

4. "Can the user reproduce my validation?" Not "I verified it" but "run these commands and you'll see [expected output]."

5. "Am I making assumptions?" Not "restart should fix it" but "tested restart, here's before/after evidence."

6. "Would I accept this from a coworker?" Not "I think this will work" but "I've proven this works."

Recovery from Violations

If you catch yourself violating proof-of-work:

1. STOP: do not send the completion claim 2. Run the validation: actually test the assumption 3. Capture evidence: document what you find 4. Update your claim: replace assumption with proof

The Ultimate Red Flag

Thought: "I don't need to test this, it's obvious it will work."

Reality: Nothing is obvious. Everything must be proven.

Recovery: Test it anyway. Evidence beats intuition.

Cargo Cult Summary

The fundamental cargo cult error is using code or patterns you cannot explain. If you cannot teach it to someone else, you do not understand it. If you do not understand it, do not ship it.

See anti-cargo-cult.md for the complete understanding verification protocol.

Retry Protocol

When an agent's output fails contract validation, retry with specific feedback instead of re-dispatching from scratch.

How It Works

1. Agent completes work and writes findings file 2. Contract validator runs (see output-contracts.md) 3. If PASS: accept findings, continue workflow 4. If FAIL: generate retry prompt from validation result

Retry Prompt Template

The retry prompt combines the validation feedback with the original task:

## Contract Validation Failed: Retry Required

{validator.retry_feedback() output}

## Original Task (unchanged)

{original dispatch prompt}

## Instructions

Fix ONLY the issues listed above.
Do not redo work that already meets the contract.
This is retry {N} of {retry_budget}.

Retry Budget

Each output contract specifies a retry_budget (default: 2).

• Retry 1: Agent gets specific feedback, retries.
• Retry 2: Agent gets updated feedback, retries.
• Budget exhausted: Failure escalated to parent with

full validation detail.

Escalation on Budget Exhaustion

When retries are exhausted, the parent receives:

## Agent Failed Contract Validation

Agent: {agent-name}
Task: {original task summary}
Retries attempted: {retry_budget}

### Last Validation Result

{final validation detail}

### Recommendation

The agent could not meet the output contract after
{retry_budget} retries. Options:
1. Adjust the contract (lower evidence threshold)
2. Assign to a different agent with more context
3. Split the task into smaller pieces
4. Escalate for human review

Key Principles

• Specific over generic: Retry feedback names

exact missing elements, not "try harder."

• Preserve prior work: The retry prompt tells the

agent not to redo passing sections.

• Bounded attempts: The retry budget prevents

infinite loops.

• Transparent failure: When budget is exhausted,

the parent gets full context to make a decision.

TodoWrite Patterns

Naming Convention

Pattern: skill-name:step-name

Evidence Logging Steps

evidence-logging:log-initialized
evidence-logging:commands-captured
evidence-logging:citations-recorded
evidence-logging:artifacts-indexed

Diff Analysis Steps

diff-analysis:context-established
diff-analysis:changes-categorized
diff-analysis:risks-assessed
diff-analysis:recommendations-formed

Catchup Steps

catchup:scope-identified
catchup:changes-analyzed
catchup:summary-generated

Review Core Steps

review-core:context-gathered
review-core:analysis-performed
review-core:findings-documented
review-core:report-assembled

Task Deletion (Claude Code 2.1.20+)

TaskUpdate now supports deleting tasks. For imbue skills, keep proof-of-work items as audit trails. Only delete transient tracking items from completed workflows.

2.1.21 fix: Task IDs are no longer reused after deletion. On 2.1.20, deleting a task and creating a new one could silently reuse the same ID, leaking old state into new tasks. Upgrade to 2.1.21+ if using task deletion.

Safe to Delete

• Transient workflow items after successful completion (e.g., catchup:scope-identified after catchup finishes)

Never Delete

• proof:* items: these are audit evidence
• evidence-logging:* items: these document captured evidence
• Any items that serve as compliance records

Best Practices

1. Use lowercase for both skill name and step name 2. Use hyphens to separate words 3. Keep step names short but descriptive 4. Progress sequentially through steps 5. Mark complete immediately after finishing step

Validation Protocols

Detailed testing protocols for common completion scenarios.

Protocol Types

1. Configuration Validation

Use when: Setting up tools, environments, services

Steps: 1. Verify prerequisites exist

   # Example: Check dependencies
   which pylsp typescript-language-server
   python --version
   npm --version

2. Test configuration loads

   # Example: Validate config file
   cat .cclsp.json | jq '.'  # Validates JSON syntax

3. Attempt service start

   # Example: Start service in test mode
   CCLSP_CONFIG_PATH=./config.json npx cclsp@latest &
   sleep 2
   ps aux | grep cclsp

4. Verify service responds

   # Example: Health check or simple query
   curl localhost:8080/health
   # OR check logs for successful initialization

Acceptance Criteria:

• [ ] All prerequisites found in $PATH
• [ ] Configuration file parses without errors
• [ ] Service starts without fatal errors
• [ ] Service responds to basic queries
• [ ] Logs show expected initialization messages

---

2. Installation Validation

Use when: Installing packages, tools, binaries

Steps: 1. Verify installation command succeeds

   npm install -g cclsp
   echo $?  # Must be 0

2. Check binary is in PATH

   which cclsp
   # Must return a path, not "not found"

3. Test version/help output

   cclsp --version  # OR --help
   # Must return valid output, not command not found

4. Run smoke test

   # Example: Minimal invocation
   cclsp setup --dry-run

Acceptance Criteria:

• [ ] Installation exits with code 0
• [ ] Binary is executable and in $PATH
• [ ] Version/help commands work
• [ ] Smoke test completes successfully

---

3. Integration Validation

Use when: Integrating multiple components (e.g., LSP, MCP, and Claude)

Steps: 1. Test each component in isolation

   # Component A
   pylsp --help  # PASS - Works standalone

   # Component B
   npx cclsp@latest --help  # PASS - Works standalone

2. Test pairwise integration

   # A + B together
   CCLSP_CONFIG_PATH=config.json npx cclsp@latest &
   # Check if cclsp can communicate with pylsp

3. Test full stack integration

   # Start Claude Code with all components
   ENABLE_LSP_TOOL=1 claude
   # Inside Claude: test LSP tool availability

4. Verify end-to-end flow

   # User action -> through stack -> expected result
   # Example: "find definition of X" -> LSP query -> result returned

Acceptance Criteria:

• [ ] Each component works in isolation
• [ ] Pairwise integration succeeds
• [ ] Full stack starts without errors
• [ ] End-to-end user flow completes successfully
• [ ] Logs show proper component communication

---

4. Bug/Issue Research Validation

Use when: Recommending solutions that could have known issues

Steps: 1. Check GitHub issues for project

   <web search: "github {project} issues {version} {keywords}">
   # Example: "github anthropics claude-code issues 2.0.76 LSP"

2. Search recent release notes

   <web search: "{project} release notes {version} changelog">
   # Look for breaking changes, known issues

3. Check community forums/discussions

   <web search: "{project} {feature} not working {version}">
   # Reddit, HackerNews, Stack Overflow

4. Verify version compatibility matrix

   # Check docs for supported versions
   <web search: "{dependency} compatibility {version}">

Acceptance Criteria:

• [ ] Searched GitHub issues for known bugs
• [ ] Checked release notes for breaking changes
• [ ] Reviewed community reports of problems
• [ ] Verified version compatibility
• [ ] Documented any blockers found

---

5. Code/Script Validation

Use when: Writing or recommending code/scripts

Steps: 1. Syntax check

   # Python
   python -m py_compile script.py

   # Bash
   bash -n script.sh

   # JavaScript/TypeScript
   npx tsc --noEmit file.ts

2. Linting check

   # Python
   ruff check script.py

   # Bash
   shellcheck script.sh

   # JavaScript
   eslint file.js

3. Dry-run or safe execution

   # Many tools support --dry-run, --check, or --simulate
   ansible-playbook playbook.yml --check
   terraform plan  # Not apply

4. Test with sample data

   # Run script with non-production test data
   python script.py --input test_data.json

Acceptance Criteria:

• [ ] Code passes syntax validation
• [ ] Linter reports no critical issues
• [ ] Dry-run succeeds without errors
• [ ] Test execution produces expected output
• [ ] No destructive actions in test mode

---

6. Environment/Dependency Validation

Use when: Assuming environment state or dependencies

Steps: 1. Check environment variables

   echo $REQUIRED_VAR
   # Must be set and non-empty

2. Verify file/directory existence

   ls -la /expected/path/to/config
   # Must exist with correct permissions

3. Check network connectivity (if applicable)

   ping -c 1 required-service.com
   curl -I https://api.example.com/health

4. Validate credentials/auth (if applicable)

   # Test auth without side effects
   gh auth status
   aws sts get-caller-identity

Acceptance Criteria:

• [ ] Required env vars are set
• [ ] Expected files/dirs exist
• [ ] Network dependencies are reachable
• [ ] Authentication works
• [ ] Permissions are correct

---

Protocol Selection Guide

Evidence Capture Template

For each protocol step, capture:

### [Protocol Name] - Step [N]: [Step Description]

**Command:**

<exact command run>

**Output:**

<relevant output, truncated if long>

**Result:** PASS / FAIL / WARNING

**Notes:**
- Any unexpected behavior
- Workarounds applied
- Decisions made

Combining Protocols

Complex scenarios often need multiple protocols:

Example: "Set up LSP in Claude Code"

1. Installation Validation - Verify pylsp, cclsp installed 2. Configuration Validation - Test .mcp.json, .cclsp.json valid 3. Integration Validation - Verify Claude → cclsp → pylsp chain 4. Bug/Issue Research - Check for known issues in current versions 5. Environment Validation - Confirm ENABLE_LSP_TOOL set

Only after ALL protocols pass can you claim "LSP is set up".