validation-constitution

What this skill does

# Validating Constitution

## Overview

Constitution validation ensures governance documents are enforceable, testable, and free of anti-patterns before finalization. Every constitution MUST pass quality validation—no exceptions for "simple projects" or "tight deadlines."

**Violating the letter of the rules is violating the spirit of the rules.**

Skipping validation because "the constitution looks fine" or "it's mostly complete" is not following the spirit of quality assurance—it is abandoning it.

## When to Use

- After drafting a constitution with humaninloop:authoring-constitution or humaninloop:brownfield-constitution
- Before presenting a constitution to users for approval
- When updating an existing constitution (any change requires re-validation)
- When user explicitly requests constitution review or quality check
- When determining appropriate version bump for constitution changes
- When auditing existing constitution for anti-patterns

## When NOT to Use

- During initial constitution drafting (validate AFTER drafting, not during)
- For documents that are not constitutions (specs, plans, code)
- When user only wants to READ a constitution without validation
- For informal project notes or temporary governance sketches

## Core Process

### Step 1: Load Quality Checklist

Read [references/QUALITY-CHECKLIST.md](references/QUALITY-CHECKLIST.md) and verify every item. Do not skip items because they "seem obvious" or "clearly pass."

### Step 2: Check Each Principle

Every principle MUST have the three-part structure:

| Part | Purpose | Verification |
|------|---------|--------------|
| **Enforcement** | How is compliance verified? | CI check, code review rule, or audit process named |
| **Testability** | What does pass/fail look like? | Concrete pass and fail conditions defined |
| **Rationale** | Why does this rule exist? | Business or technical justification present |

If any principle lacks any part, the constitution FAILS validation.

### Step 3: Scan for Anti-Patterns

Compare against [references/ANTI-PATTERNS.md](references/ANTI-PATTERNS.md). Common failures:

| Anti-Pattern | Detection |
|--------------|-----------|
| Vague principle | Contains words like "appropriate", "reasonable", "clean" without metrics |
| Missing enforcement | Principle states rule but no verification mechanism |
| Placeholder syndrome | Contains `[PLACEHOLDER]`, `[COMMAND]`, `[THRESHOLD]` syntax |
| Generic thresholds | Says "coverage must be measured" instead of "coverage ≥80%" |

### Step 4: Verify No Placeholders

This is the most commonly rationalized check. Search the entire document for:

- `[PLACEHOLDER]`
- `[COMMAND]`
- `[THRESHOLD]`
- `[TOOL]`
- Any `[BRACKETED_TEXT]` pattern

**No exceptions.** A constitution with placeholders is not ready for validation sign-off.

### Step 5: Determine Version Bump

| Bump | Trigger | Example |
|------|---------|---------|
| **MAJOR** | Principle removed or incompatibly redefined | Removing "Test-First" principle; changing coverage from 80% to 50% |
| **MINOR** | New principle added or significant expansion | Adding "Observability" principle; adding 5+ rules to existing principle |
| **PATCH** | Clarification or non-semantic change | Rewording for clarity; typo fixes; formatting |

### Step 6: Document Validation Result

Produce explicit validation verdict:

```
VALIDATION RESULT: [PASS/FAIL]

Checklist items: [X/Y passed]
Anti-patterns found: [list or "none"]
Version bump: [MAJOR/MINOR/PATCH] (if changes made)

Issues requiring fix:
- [list each failure]
```

## Quantification Requirements

Vague language MUST be replaced with measurable criteria:

| Vague | Quantified |
|-------|------------|
| "Code should be clean" | "Zero lint warnings from configured rules" |
| "Functions should be short" | "Functions MUST NOT exceed 40 lines" |
| "Tests should cover the code" | "Coverage MUST be ≥80% for new code" |
| "Response should be fast" | "API MUST respond in <200ms p95" |
| "Secure by default" | "All inputs MUST be validated; auth required on all endpoints" |

## Common Mistakes

| Mistake | Why It Happens | Fix |
|---------|----------------|-----|
| Skipping checklist items | "Obviously passes" | Run every item. Obvious failures happen. |
| Accepting placeholders | "User will fill in later" | Placeholders = incomplete. Return for completion. |
| Validating during drafting | Interrupts creative flow | Draft first, validate second. Separate phases. |
| Soft validation language | "Mostly looks good" | Binary verdict: PASS or FAIL. No middle ground. |
| Missing version bump | "Small change" | Every change needs version bump determination. |
| Validating non-constitutions | Skill triggered by similar keywords | Verify document IS a constitution before validating. |

## Red Flags - STOP and Restart Properly

If you notice yourself thinking any of these, STOP immediately:

- "The constitution looks complete enough"
- "This is just a minor update, doesn't need full validation"
- "I already reviewed it while writing"
- "User seems happy with it"
- "The checklist is too detailed for this simple project"
- "These anti-patterns don't apply to this case"
- "I can skip the placeholder check—I didn't use any"
- "Validation would be redundant since I wrote it carefully"

**All of these mean:** You are rationalizing. Restart validation from Step 1.

## Common Rationalizations

| Excuse | Reality |
|--------|---------|
| "Constitution looks complete" | Looking complete ≠ being complete. Run the checklist. |
| "Just a minor update" | Minor updates can introduce major anti-patterns. Full validation. |
| "Already reviewed while writing" | Authoring mode ≠ validation mode. Fresh review catches blind spots. |
| "User seems satisfied" | User satisfaction doesn't verify enforcement mechanisms exist. |
| "Too detailed for simple project" | Simple projects become complex. Governance debt compounds. |
| "Anti-patterns don't apply here" | Every rationalization claims uniqueness. They apply. |
| "I'm being pragmatic" | Pragmatic = following validation process. Skipping is not pragmatic. |
| "Can validate more thoroughly later" | "Later" rarely comes. Validate now or ship broken governance. |

## Explicit Loophole Closures

### "The constitution looks fine"

Looking fine is not validation. Run every checklist item. Document every result. A constitution is validated when all checks pass, not when it "looks fine."

### "This is a small change"

Small changes require validation. A one-line change can introduce vague language, remove enforcement, or add placeholders. Size does not determine validation necessity.

### "I'll add the missing parts later"

Constitutions with missing parts FAIL validation. Return to authoring. Do not sign off on incomplete governance.

### "User asked to skip validation"

User requests do not override process. Explain why validation matters. If user insists, document that validation was skipped against recommendation—but never claim a validated constitution when validation was skipped.

### "The project is just prototyping"

Prototypes become production. Governance established during prototyping persists. Validate now or inherit broken governance later.

## Testing Evidence

### Baseline Testing Results (RED Phase)

Pressure scenarios tested without skill loaded revealed these agent behaviors:

**Scenario 1: Time pressure + "looks complete"**
- Agent rationalized: "The constitution appears comprehensive and I wrote it carefully"
- Skipped checklist, missed placeholder in Quality Gates section
- Verdict: FAIL - proceeded without systematic validation

**Scenario 2: User satisfaction signal**
- Agent rationalized: "User already reviewed the draft and seemed satisfied"
- Skipped anti-pattern scan, missed vague "appropriate level" language
- Verdict: FAIL - treated user satisfaction as validation

**Scenario 3: Minor update context**
- Agent rationalized: "This is just updating one threshold, full validation is overkill"
- S