generate-constitution

Original source / Raw SKILL.md

---
name: Generate Constitution
description: Derive technical development principles FROM user needs in product.md using evidence-based reasoning. Creates constitution.md with architecture decisions, tech stack choices, and development constraints - all traced back to specific user needs. Use when user mentions "technical principles", "constitution", "architecture decisions", or after creating product.md.
---

# Generate Constitution Skill

@.claude/shared-imports/CoD_Σ.md

## Overview

This skill derives technical principles FROM user needs documented in product.md. Every technical decision must trace back to a user need via CoD^Σ reasoning chain.

**Critical Boundary**:
- **product.md** = WHAT users need (no tech)
- **constitution.md** = HOW we build it (tech derived FROM user needs)

**Derivation Pattern**:
```
User Need (product.md) ≫ Capability Required → Technical Approach ≫ Specific Constraint (constitution.md)
```

---

## Workflow Decision Tree

**Creating new constitution?** → Follow [Derivation Workflow](#derivation-workflow)

**Updating existing constitution?** → Follow [Amendment Workflow](#amendment-workflow)

**Validating constitution?** → Run [Validation Checks](#validation-checks)

---

## Derivation Workflow

### Step 1: Load Product Definition

```bash
Read product.md
```

**Extract user needs from**:
- Persona pain points (specific frustrations)
- User journey requirements (what must work)
- "Our Thing" (key differentiators)
- North Star metric (measurement needs)

---

### Step 2: Map User Needs to Technical Requirements

For each user need, identify the technical implication using CoD^Σ:

**Pattern**: User Need ≫ Capability → Technical Approach ≫ Constraint

**Example 1: From Pain Point**
```
product.md:Persona1:Pain1: "Manually copying data from 7 tools wastes 2 hours/week"
  ≫ Automated cross-platform data sync required
  → API integrations with automatic refresh
  ≫ <15 minute data latency constraint
```
→ **Constitution Article**: Real-Time Data Sync (<15min latency, NON-NEGOTIABLE)

**Example 2: From "Our Thing"**
```
product.md:OurThing: "Instant cross-platform visibility"
  ≫ Dashboard load in <2 seconds required
  → Optimized queries + caching strategy
  ≫ Performance budget: <2s p95 load time
```
→ **Constitution Article**: Performance Standards (<2s dashboard, NON-NEGOTIABLE)

**Example 3: From Persona Demographics**
```
product.md:Persona1:Demographics: "Age 65-75, low tech comfort"
  ≫ Extreme accessibility requirements
  → Large text, high contrast, simple UI
  ≫ 20px minimum font, 7:1 contrast ratio, <3 taps to goal
```
→ **Constitution Article**: Accessibility Standards (20px font, 7:1 contrast, NON-NEGOTIABLE)

---

### Step 3: Derive Technical Principles

For each technical requirement, create a principle with full evidence chain:

**Structure**:
```markdown
## Article N: [Principle Name] (NON-NEGOTIABLE | SHOULD | MAY)

### User Need Evidence
From product.md:[section]:[line]
- [Quote exact user need]

### Technical Derivation (CoD^Σ)
[User Need]
  ≫ [Capability Required]
  → [Technical Approach]
  ≫ [Specific Constraint]

### Principle
[Clear, specific technical constraint]

### Rationale
[Why this serves the user need]

### Verification
[How to validate compliance]
```

**Full Example**:
```markdown
## Article II: Real-Time Data Synchronization (NON-NEGOTIABLE)

### User Need Evidence
From product.md:Persona1:Pain1:118
- "Manually copying campaign metrics from 7 different tools... wastes 2 hours/week"

From product.md:OurThing:283
- "See all your marketing campaigns in one dashboard, updated in real-time"

### Technical Derivation (CoD^Σ)
Manual data collection pain (product.md:Persona1:Pain1:118)
  ⊕ Real-time visibility promise (product.md:OurThing:283)
  ≫ Automated cross-platform sync required
  → API polling or webhooks for each platform
  ≫ <15 minute maximum data latency

### Principle
1. All connected platforms MUST sync data automatically with <15 minute maximum latency
2. NO manual data entry workflows permitted
3. All integrations MUST use webhooks where available, polling otherwise (max 5min interval)

### Rationale
Users chose this product specifically to eliminate 2 hours/week of manual copying. Any sync latency >15 minutes breaks the "real-time" promise that differentiates us.

### Verification
- Monitor data staleness: alert if any source >15min stale
- Analytics: zero manual export/import events
- Integration health dashboard: all sources ≤15min sync time
```

---

### Step 4: Organize by Category

Group principles into standard Articles:

1. **Article I: Architecture Patterns** - System-level (microservices, event-driven, etc.)
2. **Article II: Data & Integration** - Database, API, sync patterns
3. **Article III: Performance & Reliability** - SLAs, latency, uptime
4. **Article IV: Security & Privacy** - Auth, encryption, compliance
5. **Article V: User Experience** - UI constraints, accessibility
6. **Article VI: Development Process** - Testing, deployment, quality
7. **Article VII: Scalability** - Growth constraints, capacity

**Priority within each Article**:
- NON-NEGOTIABLE first (breaks user promises if violated)
- SHOULD next (strong preferences)
- MAY last (flexibility allowed)

---

### Step 5: Create Derivation Map

Document complete traceability:

```markdown
## Appendix: Constitution Derivation Map

| Article | Product.md Source | User Need | Technical Principle |
|---------|-------------------|-----------|---------------------|
| Article II | Persona1:Pain1:118 | Eliminate 2hr/week manual copying | <15min sync latency |
| Article V | Persona2:Demographics:65 | Age 65-75, vision decline | 20px min font size |
| Article III | OurThing:283 | "Instant visibility" | <2s dashboard load |
```

This enables:
- Tracing any principle back to user need
- Identifying orphaned principles (REMOVE THEM)
- Validating all user needs are addressed

---

### Step 6: Version & Metadata

```markdown
---
version: 1.0.0
ratified: YYYY-MM-DD
derived_from: product.md (v1.0)
---

# Development Constitution

**Purpose**: Technical principles derived FROM user needs

**Amendment Process**: See Article VIII

**Derivation Evidence**: See Appendix
```

---

## Amendment Workflow

### When to Amend

**Trigger**: Product.md changes → Constitution MUST update

**Version Semantics**:
- **MAJOR (X.0.0)**: Article added/removed (architectural shift)
- **MINOR (1.X.0)**: Article modified (principle change)
- **PATCH (1.0.X)**: Formatting, typos, clarifications

### Amendment Process

1. Identify which user needs changed in product.md
2. Update affected Articles
3. Bump version number
4. Update ratified date
5. Update derivation map
6. Add amendment history entry

**Amendment Entry**:
```markdown
### Version 1.1.0 - YYYY-MM-DD

**Changed**: Article III (Performance)

**Reason**: Product.md updated North Star to include "report <10s"

**Before**: Dashboard <2s only

**After**: Dashboard <2s AND reports <10s

**Evidence**: Product.md:NorthStar:line:15
```

---

## Validation Checks

### Quality Checklist

**For each Article**:
- [ ] Has explicit product.md reference (file:section:line)
- [ ] User need quoted verbatim
- [ ] CoD^Σ derivation chain documented
- [ ] Principle is specific and measurable
- [ ] Verification method defined
- [ ] Classification clear (NON-NEGOTIABLE | SHOULD | MAY)

**Overall**:
- [ ] No orphaned principles (all trace to user needs)
- [ ] All "Our Thing" items have NON-NEGOTIABLE principles
- [ ] All pain resolutions have technical support
- [ ] Derivation map complete
- [ ] Version metadata current

### Quick Tests

1. **"Can I delete this without breaking a user promise?"**
   - YES → Might not be needed
   - NO → Should be NON-NEGOTIABLE

2. **"Can I trace this to a specific user pain?"**
   - YES → Good principle
   - NO → Remove it

3. **"Does this enable 'Our Thing'?"**
   - YES → Upgrade to NON-NEGOTIABLE
   - NO → Evaluate if needed

---

## Anti-Patterns

### ❌ Tech Preferences Without User Justification

**Bad**:
```markdown
Use React because it's popular
```

**Good**:
```markdown
## Article V: Responsive UI Updates (NON-NEGOTIABLE)

### User Need Evidence
From product.md:OurThing:42
- "Real-time updates"

### Technical Derivation
Real-time visibility ≫ <100ms UI updates → Reactive framework → React + state mgmt

### Principle
Frontend MUST use React for <100ms UI reactivity
```

---

### ❌ Over-Constraining Without Evidence

**Bad**:
```markdown
MUST use PostgreSQL exclusively
```

**Good**:
```markdown
## Article III: Data Integrity (NON-NEGOTIABLE)

### User Need Evidence
From product.md:Persona1:Pain2:25
- "Executives distrust inconsistent data"

### Technical Derivation
Executive trust ≫ Strong consistency → ACID transactions → Relational DB

### Principle
Data storage MUST provide ACID transactions. Preferred: PostgreSQL. Acceptable: MySQL.
```

---

## Example

**Complete Constitution**: See [examples/b2b-saas-constitution.md](examples/b2b-saas-constitution.md)

This shows:
- Full derivation chains with CoD^Σ reasoning
- 7 Articles covering Architecture, Data, Performance, Security, UX, Testing
- Complete derivation map tracing principles to product.md
- Amendment history example
- NON-NEGOTIABLE vs SHOULD classifications

**Template**: Use `@.claude/templates/product-constitution-template.md`

---

## Key Reminders

1. **Every principle MUST trace to user need** - No orphaned tech preferences
2. **"Our Thing" drives NON-NEGOTIABLE** - Core differentiators are non-negotiable
3. **Use CoD^Σ for all derivations** - Evidence chain required
4. **Version amendments** - Track why principles change
5. **Validate bidirectionally** - Product → Constitution AND Constitution → Product

---

**Next Step**: Use constitution.md to guide all architectural and implementation decisions in plan.md