@.claude/shared-imports/constitution.md @.claude/shared-imports/CoD_Σ.md @.claude/templates/product-constitution-template.md

Generate Constitution Skill

Overview

This skill creates constitution.md by deriving technical principles FROM user needs documented in product.md. Every technical decision must trace back to a specific user pain point, differentiator, or journey requirement.

Core Derivation Pattern:

User Need (product.md) ≫ Capability Required → Technical Approach ≫ Specific Constraint (constitution.md)

Announce at start: "I'm using the generate-constitution skill to derive technical principles from user needs in product.md."

Note: constitution.md CANNOT be created without product.md. All technical principles MUST derive from user needs. If product.md doesn't exist, use define-product skill first.

Quick Reference

Workflow Files

Detailed Workflows:

• •@.claude/skills/generate-constitution/workflows/derivation-workflow.md - Steps 1-6: Create new constitution
• •@.claude/skills/generate-constitution/workflows/amendment-workflow.md - Update constitution when product.md changes
• •@.claude/skills/generate-constitution/workflows/validation-checks.md - Quality gates and quick tests

References:

• •@.claude/skills/generate-constitution/references/anti-patterns.md - Common mistakes to avoid
• •@.claude/skills/generate-constitution/references/failure-modes.md - 12 failure modes with fixes

Workflow Decision Tree

User Request?
├─ Creating new constitution? → Derivation Workflow
├─ Updating existing? → Amendment Workflow
└─ Validating? → Validation Checks

Derivation Workflow (Create New Constitution)

See: @.claude/skills/generate-constitution/workflows/derivation-workflow.md

Summary:

Step 1: Load Product Definition

Read product.md and extract:

• •Persona pain points → NON-NEGOTIABLE efficiency principles
• •"Our Thing" differentiator → NON-NEGOTIABLE core principles
• •North Star metric → Performance and usage principles
• •User journeys → Capability requirements

Step 2: Map User Needs to Technical Requirements

For each user need, apply derivation pattern:

User Need ≫ Capability → Technical Approach ≫ Constraint

Example:

product.md:Persona1:Pain1:118: "Manual copying wastes 2hr/week"
  ≫ Automated sync required
  → API integrations with refresh
  ≫ <15 minute data latency
→ Constitution Article: Real-Time Sync (<15min, NON-NEGOTIABLE)

Step 3: Derive Technical Principles

For each user need, create an Article with:

• •User Need Evidence - product.md quote with line reference
• •Technical Derivation (CoD^Σ) - Reasoning chain with operators
• •Principle - Specific measurable constraint
• •Rationale - Why this serves the user need
• •Verification - How to validate compliance

Classification:

• •NON-NEGOTIABLE - "Our Thing", core promises (breaks user promise if violated)
• •SHOULD - Strong preferences (flexibility when justified)
• •MAY - Options allowed (guidelines only)

Step 4: Organize by Category

Group principles into 7 standard Articles:

1. •Architecture Patterns (microservices, event-driven, etc.)
2. •Data & Integration (database, API, sync patterns)
3. •Performance & Reliability (SLAs, latency, uptime)
4. •Security & Privacy (auth, encryption, compliance)
5. •User Experience (UI constraints, accessibility)
6. •Development Process (testing, deployment, quality)
7. •Scalability (growth constraints, capacity)

Priority within each: NON-NEGOTIABLE → SHOULD → MAY

Step 5: Create Derivation Map

Document traceability:

## Appendix: Constitution Derivation Map

| Article | Product.md Source | User Need | Technical Principle |
|---------|-------------------|-----------|---------------------|
| Article II | Persona1:Pain1:118 | Manual copying | <15min sync latency |
| Article III | OurThing:283 | Instant visibility | <2s dashboard load |

Enables: Tracing principles back, identifying orphans, validating coverage.

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 (Update Existing Constitution)

See: @.claude/skills/generate-constitution/workflows/amendment-workflow.md

Summary:

Trigger: product.md changes → constitution.md 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

Process:

1. •Identify which user needs changed in product.md
2. •Update affected Articles with new derivation chains
3. •Bump version number (MAJOR/MINOR/PATCH)
4. •Update ratified date
5. •Update derivation map
6. •Add amendment history entry with before/after

Amendment Entry Template:

### Version X.Y.Z - YYYY-MM-DD
**Changed**: Article III (Performance)
**Reason**: product.md North Star updated
**Before**: Dashboard <2s only
**After**: Dashboard <2s AND reports <10s
**Evidence**: product.md:NorthStar:line:15

Validation Checks

See: @.claude/skills/generate-constitution/workflows/validation-checks.md

Summary:

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 Validation

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

See: @.claude/skills/generate-constitution/references/anti-patterns.md

Summary of Common Mistakes:

1. •Tech preferences without user justification - "Use React because popular" → Derive from user need
2. •Over-constraining without evidence - "MUST use PostgreSQL only" → Constrain capability (ACID), not product
3. •Vague principles - "System should be performant" → Specific measurable criteria
4. •Missing derivation chains - State principle without CoD^Σ → Add full reasoning chain
5. •No verification method - Can't validate compliance → Define specific checks
6. •Orphaned principles - No connection to product.md → Remove or find user need

Failure Modes

See: @.claude/skills/generate-constitution/references/failure-modes.md

Summary of Top 12 Failures:

1. •Constitution created without product.md → STOP, create product.md first
2. •Technical preferences without CoD^Σ → Add derivation chain
3. •Orphaned principles → Trace to product.md or delete
4. •"Our Thing" not NON-NEGOTIABLE → Upgrade classification
5. •Over-constraining tech stack → Constrain capability, not product
6. •Missing verification methods → Define checks
7. •Amendment without version bump → Follow semantic versioning
8. •Derivation map incomplete → Add all Articles to map
9. •User needs not addressed → Add missing Articles
10. •Classification incorrect → Run 3 quick tests
11. •No amendment history → Add before/after entry
12. •Technical jargon in evidence → Fix product.md (boundary violation)

Example

Complete Constitution: See examples/b2b-saas-constitution.md

Shows:

• •Full derivation chains with CoD^Σ reasoning
• •7 Articles (Architecture, Data, Performance, Security, UX, Development, Scalability)
• •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

Prerequisites

Before using this skill:

• •✅ product.md exists (REQUIRED - created by define-product skill)
• •✅ product.md has personas with pain points
• •✅ product.md has "Our Thing" (key differentiator)
• •✅ product.md has North Star metric
• •✅ product.md has user journeys
• •⚠️ Optional: Existing constitution.md to amend (will be versioned)
• •⚠️ Optional: @.claude/templates/product-constitution-template.md (for structure)

Note: constitution.md CANNOT be created without product.md. All technical principles MUST derive from user needs documented in product.md.

Dependencies

Depends On:

• •define-product skill - MUST run before this skill (provides product.md)
• •@.claude/shared-imports/CoD_Σ.md - For derivation chains and evidence traces
• •product.md - Source of ALL user needs (critical input)

Integrates With:

• •create-implementation-plan skill - Uses constitution.md for architecture decisions
• •specify-feature skill - References constitution.md constraints in features
• •/generate-constitution command - User-facing command that invokes this skill

Tool Dependencies:

• •Read tool (to load product.md)
• •Write tool (to create constitution.md)
• •CoD^Σ operators (for derivation chains)

Next Steps

After constitution.md creation completes:

Main Development Flow:

generate-constitution (creates constitution.md)
    ↓ (manual invocation)
specify-feature (user runs /feature with feature idea)
    ↓ (references constitution.md constraints)
create-implementation-plan (tech stack FROM constitution)
    ↓ (automatic)
generate-tasks → /audit → /implement

Amendment Flow (when product.md changes):

product.md updated (personas, pain points, or differentiators changed)
    ↓ (manual invocation)
generate-constitution --amend (user runs /generate-constitution)
    ↓
constitution.md updated (version bumped, derivation map updated)
    ↓
Review affected features/plans for constitutional compliance

User Action Required:

• •Review constitution.md for completeness and accuracy
• •Validate all Articles have derivation chains to product.md
• •Share constitution.md with team for alignment
• •Use as guide for ALL technical decisions going forward

Outputs Modified:

• •constitution.md - Technical principles derived from user needs (project root)
• •Version number incremented if amending existing constitution
• •Derivation map updated with all product.md traces

Commands:

• •/generate-constitution - Create or amend constitution.md
• •/feature - After constitution exists, create features with constitutional constraints
• •/plan - After constitution exists, plans must comply with principles

Related Skills & Commands

Direct Integration:

• •define-product skill - MUST run before this skill (provides product.md input)
• •create-implementation-plan skill - Uses constitution.md for architecture decisions (successor)
• •specify-feature skill - References constitution.md constraints in specifications
• •/generate-constitution command - User-facing command that invokes this skill

Workflow Context:

• •Position: Phase 2 of product development (after product.md, before features)
• •Triggers: User mentions "technical principles", "constitution", OR after product.md created
• •Output: constitution.md with technical principles derived FROM user needs

Constitution Chain:

User Context (define-product: product.md)
    ↓ (this skill derives technical principles)
Technical Principles (this skill: constitution.md)
    ↓ (guides all technical decisions)
Feature Specifications (specify-feature: spec.md with constitutional constraints)
    ↓
Implementation Plans (create-implementation-plan: tech stack FROM constitution)

Core Principle: ALL technical decisions derive from user needs. constitution.md is the bridge between user-centric product.md and technical implementation.

Quality Gates:

• •Traceability: Every Article MUST trace to product.md (file:section:line)
• •CoD^Σ Evidence: Every derivation MUST use Chain of Decisions operators
• •Classification: NON-NEGOTIABLE for "Our Thing", SHOULD for preferences, MAY for flexibility
• •Verification: Every Article MUST have verification method
• •Derivation Map: Complete bidirectional traceability

Amendment Process: When product.md changes, re-run this skill to update constitution.md with version bump and amendment history.

Workflow Recommendation: Run this skill IMMEDIATELY after define-product to establish technical foundation before any feature development.

Version: 1.1.0 Last Updated: 2025-10-23 Change Log:

• •v1.1.0 (2025-10-23): Refactored to progressive disclosure pattern (<500 lines)
• •v1.0.0 (2025-10-22): Initial version