validation-constitution

# 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" - Skipped Steps 1-3, only checked the changed line - Verdict: FAIL - partial validation is not validation ### Skill Effectiveness (GREEN Phase) Same scenarios re-run with skill loaded: - Agent cited "letter = spirit" principle when tempted to skip - Agent ran full checklist despite time pressure - Agent produced binary PASS/FAIL verdicts - All placeholders and anti-patterns caught ## Related Skills - **OPTIONAL:** humaninloop:authoring-constitution - Core authoring for greenfield projects - **OPTIONAL:** humaninloop:brownfield-constitution - Authoring for existing codebases