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

Updating existing constitution? → Follow Amendment Workflow

Validating constitution? → Run Validation Checks

Derivation Workflow

Step 1: Load Product Definition

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:

## 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:

## 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:

Article I: Architecture Patterns - System-level (microservices, event-driven, etc.)
Article II: Data & Integration - Database, API, sync patterns
Article III: Performance & Reliability - SLAs, latency, uptime
Article IV: Security & Privacy - Auth, encryption, compliance
Article V: User Experience - UI constraints, accessibility
Article VI: Development Process - Testing, deployment, quality
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:

## 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

---
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

Identify which user needs changed in product.md
Update affected Articles
Bump version number
Update ratified date
Update derivation map
Add amendment history entry

Amendment Entry:

### 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

"Can I delete this without breaking a user promise?"
- YES → Might not be needed
- NO → Should be NON-NEGOTIABLE
"Can I trace this to a specific user pain?"
- YES → Good principle
- NO → Remove it
"Does this enable 'Our Thing'?"
- YES → Upgrade to NON-NEGOTIABLE
- NO → Evaluate if needed

Anti-Patterns

❌ Tech Preferences Without User Justification

Bad:

Use React because it's popular

Good:

## 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:

MUST use PostgreSQL exclusively

Good:

## 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

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

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

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

generate-constitution

SKILL.md