authoring-constitution

What this skill does

# Authoring Constitution

## Overview

Write project constitutions that teams actually follow. Every principle must be enforceable, testable, and justified. Vague aspirations are rejected in favor of actionable constraints with measurable criteria.

## When to Use

- User asks to "create a constitution" or "define governance"
- Starting a new greenfield project that needs governance
- User wants to "write principles" or "define constraints"
- Establishing quality gates and enforcement mechanisms
- Defining amendment processes and version policies

## When NOT to Use

- **Brownfield projects with existing code**: **REQUIRED** alternative - Use `humaninloop:brownfield-constitution` instead, which provides Essential Floor + Emergent Ceiling approach
- **Reviewing an existing constitution**: **OPTIONAL** - Use `humaninloop:validation-constitution` for quality checks
- **Syncing CLAUDE.md after constitution changes**: **OPTIONAL** - Use `humaninloop:syncing-claude-md` for synchronization

## Common Mistakes

| Mistake | Problem | Fix |
|---------|---------|-----|
| Vague principles | "Code should be clean" has no enforcement | Add specific, measurable criteria: "Functions MUST be ≤40 lines" |
| Missing enforcement | Principles without verification become suggestions | Every principle needs CI automation, code review checklist, or audit process |
| Untestable criteria | "Good architecture" can't be verified | Define binary pass/fail: "No domain imports from infrastructure layer" |
| No rationale | Future maintainers don't know why rules exist | Explain the failure mode prevented and success enabled |
| Skipping SYNC IMPACT | Constitution changes without audit trail | Always update the SYNC IMPACT REPORT header with version changes |
| CLAUDE.md drift | AI assistants operate with outdated guidance | Include CLAUDE.md Sync Mandate section; update both files together |

## The Three-Part Principle Rule

Every principle MUST have three components. A principle without all three is incomplete and should not be accepted.

### 1. Enforcement

How compliance is verified. Without enforcement, a principle is a suggestion.

```markdown
**Enforcement**:
- CI runs `ruff check .` and blocks merge on violations
- Code review MUST verify test files accompany new functionality
- Quarterly audit checks exception registry for staleness
```

**Enforcement Types**:

| Type | Examples | Strength |
|------|----------|----------|
| **CI Automated** | Linting, tests, coverage gates | Strongest—no human judgment needed |
| **Code Review** | Architecture compliance, security review | Strong—explicit checklist item |
| **Tooling** | Pre-commit hooks, IDE plugins | Medium—can be bypassed |
| **Audit** | Quarterly review, compliance check | Weaker—periodic, not continuous |

### 2. Testability

What pass/fail looks like. A principle without testable criteria is merely an aspiration.

```markdown
**Testability**:
- Pass: `flutter analyze` exits with code 0
- Pass: All functions have ≤10 cyclomatic complexity
- Fail: Any file exceeds 400 lines without documented exception
```

**Testability Requirements**:
- Binary outcome (pass or fail)
- Measurable threshold where applicable
- Observable without subjective judgment
- Reproducible by any team member

### 3. Rationale

Why this constraint exists. Future maintainers need this to evaluate if the rule is still relevant.

```markdown
**Rationale**: Tests written after implementation tend to validate what was built rather than what was intended. Test-first ensures requirements drive implementation, catches defects early, and produces inherently testable, modular code.
```

**Rationale Requirements**:
- Explains the failure mode this prevents
- Describes the success this enables
- Provides context for future evaluation
- Justifies the enforcement overhead

## Principle Writing Format

```markdown
### I. [Principle Name]

[Declarative statement of the constraint using RFC 2119 keywords]

- [Specific rule 1]
- [Specific rule 2]
- [Specific rule 3]

**Enforcement**:
- [How compliance is verified]
- [Specific commands or processes]

**Testability**:
- [Pass/fail criteria]
- [Measurable thresholds]

**Rationale**: [Why this constraint exists—what failure it prevents, what success it enables]
```

## RFC 2119 Keywords

Use precise language for requirements:

| Keyword | Meaning | Example |
|---------|---------|---------|
| **MUST** | Absolute requirement; no exceptions | "Tests MUST pass before merge" |
| **MUST NOT** | Absolute prohibition | "Secrets MUST NOT be committed" |
| **SHOULD** | Recommended; valid exceptions exist | "Functions SHOULD be under 40 lines" |
| **SHOULD NOT** | Discouraged; valid exceptions exist | "Magic numbers SHOULD NOT appear" |
| **MAY** | Optional; implementation choice | "Teams MAY adopt additional linting rules" |

See [references/RFC-2119-KEYWORDS.md](references/RFC-2119-KEYWORDS.md) for detailed usage.

## Mandatory Constitution Sections

Every constitution MUST include these sections:

### 1. SYNC IMPACT REPORT (Header)

Track changes as HTML comment at file top. This provides an audit trail of constitution evolution.

```html
<!--
SYNC IMPACT REPORT
==================
Version change: X.Y.Z → A.B.C (MAJOR|MINOR|PATCH: Brief rationale)

Modified principles: [List or "None (enforcement details updated)"]

Added sections:
- [New section name]

Removed sections:
- [Removed section name] (or "None")

Configuration changes:
- [File/path change]: [old] → [new]
- [Structural change description]

Templates requiring updates:
- CLAUDE.md: [Status - updated ✅ or pending ⚠️]
- [Other templates]: [Status]

Follow-up TODOs:
- [Any deferred items] (or "None")

Previous reports:
- X.Y.Z (YYYY-MM-DD): [One-line summary of that version's changes]
- W.X.Y (YYYY-MM-DD): [One-line summary]
- ...
-->
```

**Version History Best Practice**: Maintain a rolling log of previous versions in the SYNC IMPACT REPORT. This provides:
- Quick reference for what changed when
- Context for understanding current state
- Audit trail for compliance reviews

Example from mature constitution:
```html
<!--
Previous reports:
  - 3.1.0 (YYYY-MM-DD): Added CLAUDE.md synchronization mandate
  - 3.0.0 (YYYY-MM-DD): Adopted hexagonal architecture, added strategic abstraction principle
  - 2.1.0 (YYYY-MM-DD): Added unification trigger to API consistency principle
  - 2.0.0 (YYYY-MM-DD): Added API consistency principle
  - 1.8.0 (YYYY-MM-DD): Added exception registry and process
-->
```

See [references/SYNC-IMPACT-FORMAT.md](references/SYNC-IMPACT-FORMAT.md) for complete format.

### 2. Core Principles

Numbered principles (I, II, III...) with Enforcement/Testability/Rationale.

**Naming Conventions**:
- Use Roman numerals (I, II, III, IV, V...)
- Name captures the constraint domain
- Mark non-negotiable principles explicitly: `(NON-NEGOTIABLE)`

**Common Principle Categories**:

| Category | Examples |
|----------|----------|
| **Development Process** | Test-First, Code Review, Documentation |
| **Code Quality** | Linting, Complexity Limits, Coverage |
| **Architecture** | Layer Rules, Dependency Flow, Module Boundaries |
| **Security** | Auth, Secrets, Input Validation |
| **Operations** | Observability, Error Handling, Performance |
| **Governance** | Versioning, Dependencies, Exceptions |

**Greenfield Recommendation**: Beyond the Essential Floor (I-IV: Security, Testing, Error Handling, Observability), greenfield constitutions SHOULD include architectural principles. See [references/RECOMMENDED-PATTERNS.md](references/RECOMMENDED-PATTERNS.md) for:

- **Hexagonal Architecture** (Ports & Adapters) - Layer rules, dependency flow, port interfaces
- **Single Responsibility & Module Boundaries** - Complexity limits, separation of concerns
- **Dependency Discipline** - Justification, isolation, vulnerability scanning

These patterns establish good foundations from day one. It's easier to start with architectural discipline than to retrofit it later.

### 3. Tec