defining-constitution

name	defining-constitution
description	Develops project constitutional principles through Socratic questioning. Use when establishing design values, creating project governance, or resolving ambiguous design decisions.

Project Constitution Development

Create constitutional principles so clear that both AI and human can independently evaluate feature alignment and reach the same conclusion. The project constitution serves as "supreme law" -- a clear, unambiguous statement of core design values, decision-making frameworks, concrete alignment examples, and amendment processes.

<required_context> This skill operates in four modes:

1. Constitution Creation -- When helping user create new constitution from scratch, use the initializing-governance skill instead (it includes constitution creation as part of full setup).
2. Constitution Refinement -- When user has existing constitution needing improvement (analyze for ambiguity, missing examples, conflicts).
3. Clarity Refinement (Socratic Process) -- Systematically eliminate all ambiguity through structured questioning. This is the primary value-add. Invoked with phrases like "Refine the clarity of our constitution", "Help me make Principle 3 clearer", "Remove ambiguity from our design principles".
4. Constitutional Amendments -- When user proposes changes to existing principles. </required_context>

Constitution Refinement

When user has existing constitution needing improvement:

Read Current Constitution:

# Read existing file
cat .wingman/config/CONSTITUTION.md

Analyze for Issues:

• Ambiguous language ("clean", "simple", "good" without definition)
• Missing concrete examples
• No anti-patterns documented
• Vague principles without specific applications
• Conflicting principles
• Unmeasurable criteria

Present Findings:

## Constitution Analysis

### Strengths
- [What's working well]

### Issues Found

#### Ambiguity Issues
- **Principle N**: "[Quote]" - Ambiguous because [reason]
- **Principle M**: Missing concrete examples

#### Missing Elements
- No anti-patterns documented
- No decision framework
- Unclear amendment process

#### Conflicts
- Principle X conflicts with Principle Y when [scenario]

Phase 1: Identify Ambiguities

Scan for Common Ambiguity Patterns:

Vague Quality Terms:

• "clean" - Clean to who? What defines clean?
• "simple" - Simple interface or simple implementation?
• "maintainable" - Measured how?
• "scalable" - To what scale?
• "performant" - What performance targets?

Unmeasurable Claims:

• "Fast" - Compared to what? How fast?
• "Secure" - Which threats? What security model?
• "Reliable" - What uptime? What MTBF?

Context-Dependent Terms:

• "User-friendly" - Which users? What use cases?
• "Flexible" - Flexible in what ways?
• "Robust" - Against which failure modes?

Conflicting Principles:

• "Move fast" vs "High quality" - Which wins when they conflict?
• "Simple" vs "Feature-rich" - Where's the line?

Phase 2: Socratic Questioning

For EACH ambiguity identified, ask structured questions to force specificity:

Template for Questioning:

For Vague Quality: "You say '[vague term]'. Let's make this concrete:"

1. "What would make something NOT [vague term]? Give me a specific example."
2. "If I showed you two implementations, how would you decide which is more [vague term]?"
3. "What's the worst violation of [vague term] you've seen? What made it bad?"
4. "Can you give me a checklist to verify [vague term]?"

For Unmeasurable Claim: "You want '[claim]'. How will we know we achieved it?"

1. "What's the minimum acceptable [metric]?"
2. "At what point would this be 'good enough'?"
3. "What measurement would make you confident we've succeeded?"
4. "What would failure look like? How would we detect it?"

For Context-Dependent: "You mention '[term]' - let's define the context:"

1. "Who specifically benefits from this?"
2. "In which scenarios does this matter most?"
3. "When would we explicitly NOT prioritize this?"
4. "What trade-offs are acceptable to achieve this?"

For Conflicts: "These principles could conflict. Let's resolve:"

1. "Give me a scenario where both can't be satisfied. Which wins?"
2. "What's the hierarchy - which is more important?"
3. "How do we decide when to compromise each one?"
4. "Can you reword to eliminate the conflict?"

Phase 3: Extract Concrete Specifications

From user's answers, derive concrete, verifiable criteria:

Transform Vague to Specific:

Before: "Code should be clean" After (from questioning):

**Principle**: Code Clarity Over Cleverness

**In Practice**:
- Functions limited to 50 lines maximum
- No nested ternaries or complex one-liners
- Variable names describe business concepts, not implementations
- Every function has single, obvious purpose

**Anti-patterns**:
- Combining multiple operations in single expression for brevity
- Using abbreviations or domain jargon without comments
- Functions that do "and also" (multiple responsibilities)

**Examples**:
- GOOD: `getUserByEmail(email)` with clear early returns
- BAD: `getUsr(e)` with nested if-else chains

Before: "System should be scalable" After (from questioning):

**Principle**: Scale Incrementally, Not Prematurely

**In Practice**:
- Design for 10x current load, not 1000x
- Choose boring, proven technologies over cutting-edge
- Measure before optimizing (no guessing performance)
- Accept tech debt to ship, pay it down when load demands

**Anti-patterns**:
- Adding caching/sharding before measuring need
- Choosing distributed systems for <1M users
- Optimizing code paths with no evidence of bottleneck

**Examples**:
- GOOD: Started with single Postgres, added read replicas at 100K users
- BAD: Used microservices from day 1 for 100 user MVP

Phase 4: Document Decision Framework

After refining principles, ensure decision framework exists:

Five Questions (from template):

1. Constitutional Alignment: Does this align with our core principles?
2. User Value: Does this solve a real user problem?
3. Simplicity: Is this the simplest solution that works?
4. Maintainability: Can we maintain this long-term?
5. Scope: Does this fit our mission, or is it scope creep?

Customize for Project:

• Add project-specific questions if needed
• Define what "yes" means for each question
• Give examples of features that failed each question

Phase 5: Validate with Scenarios

Test Refined Constitution against real or hypothetical features:

Process:

1. Present 3-4 feature scenarios (mix of aligned and misaligned)
2. Ask user: "Based on our principles, should we build this?"
3. You independently apply principles and decide
4. Compare answers

**Do answers align between you and the user?**

• If answers differ: Constitution still has ambiguity -- return to the socratic-questioning step.
• If answers align: Constitution is concrete enough -- proceed.

Example Scenarios:

Scenario A: "Add a visual theme customizer allowing users to change all UI colors"

• Constitutional Question: Does this align with Principle 1 (Simplicity)?
• Your analysis: [Based on principle text]
• User's answer: [Yes/No with reasoning]

Scenario B: "Build admin dashboard to view all user data"

• Constitutional Question: Does this align with Principle 3 (Privacy)?
• Your analysis: [Based on principle text]
• User's answer: [Yes/No with reasoning]

Goal: Both you and user reach same conclusion using only the written principles.

Constitutional Amendment Process

When user wants to change existing principles:

1. Create Amendment Proposal Issue

Use issues_create:

issues_create({
  title: "[CONSTITUTIONAL AMENDMENT] [Short title]",
  description: `## Amendment Proposal: [Title]

### Summary
[1-2 sentence summary of proposed amendment]

### Rationale
[Why this amendment is necessary]
[What issues it addresses]
[What improvements it achieves]

### Current Text
\`\`\`
[Exact text of current principle if modifying existing]
\`\`\`

### Proposed Text
\`\`\`
[Exact text of new/modified principle]
\`\`\`

### Impact Analysis

**Affected Specifications**: [List spec IDs]
**Affected Code**: [List files/components]
**Breaking Changes**: [Yes/No - explain]

### Potential Risks
- [Risk 1]: [Mitigation]
- [Risk 2]: [Mitigation]

### Migration Plan
[How existing code/specs will be updated to reflect new principle]
`,
  type: "issue",
  status: "open",
  priority: "high",
  labels: ["governance", "constitutional-amendment"],
  project: "Governance"
})

2. User Approval

Wait for user to explicitly approve amendment.

Don't auto-approve - constitutional changes are serious.

3. Update Constitution File

Once approved, update .wingman/config/CONSTITUTION.md:

Version increment:

• Major version (1.0.0 -> 2.0.0): New principle added or principle removed
• Minor version (1.0.0 -> 1.1.0): Existing principle modified
• Patch version (1.0.0 -> 1.0.1): Clarification or example added

Update sections:

• Increment version number in frontmatter
• Update "Last Amended" date
• Modify/add principle sections
• Add entry to Version History section
• Document in changelog

Example edit:

**Version**: 1.1.0
**Last Amended**: 2024-11-18

[... principles sections ...]

### Version History

- **1.1.0** (2024-11-18): Modified Principle 2 (Simplicity) to add concrete example about microservices
- **1.0.0** (2024-10-01): Initial constitution ratified

4. Update Roadmap Changelog

Add entry to .wingman/ROADMAP.md changelog:

## Changelog

- **2024-11-18**: Constitutional amendment 1.1.0 affects Phase 2 (modified simplicity principle)
- [...]

5. Identify Affected Specs

Search for specifications that might conflict:

# Search specs for mentions of modified principle
grep -r "Principle [N]" .wingman/specifications/*.md
grep -r "[principle keyword]" .wingman/specifications/*.md
grep -r "[principle keyword]" .wingman/config/CONSTITUTION.md

Review each affected spec and propose updates if needed.

6. Close Amendment Issue

Mark amendment issue as closed with summary:

## Amendment Complete

**Version**: [X.Y.Z]
**Date**: [YYYY-MM-DD]

**Changes Made**:
- Updated Principle [N] in .wingman/config/CONSTITUTION.md
- Version incremented to [X.Y.Z]
- Roadmap changelog updated
- [List any spec updates made]

**Migration Status**:
- [ ] All affected specs reviewed
- [ ] Code updates [N/A or completed]
- [ ] Team notified

Amendment is now in effect.

Working with Constitutional Ambiguity

Red Flags (Trigger Refinement)

If you see ANY of these in a principle, invoke clarity refinement:

• Abstract quality words: "clean", "simple", "elegant", "robust"
• No examples: Principle has no Good/Bad examples
• No anti-patterns: Doesn't say what NOT to do
• "Should" without criteria: "Code should be fast" (how fast?)
• Dependent on judgment: Requires human to interpret
• Conflicts with others: Contradicts another principle
• Can't be checked: No way to verify compliance

Clarity Heuristic

Test: Can a new LLM, given ONLY the constitution (no conversation history), evaluate a feature request and reach the same conclusion as you and the user?

If NO: Constitution needs refinement. If YES: Constitution is concrete enough.

<success_criteria>

• All principles use concrete, measurable criteria
• Every principle includes specific examples (good AND bad)
• Anti-patterns are documented explicitly
• Constitution is under 150 lines total (context limits)
• Principles reference real scenarios from the project
• All principles are actionable (compliance can be checked)
• No vague quality words without definition
• No abstract philosophy
• No more than 10 principles (too many to remember)
• Every "should" statement explains how to check compliance
• No room for interpretation remains
• When principles conflict, resolution is explicit (hierarchy or rewrite) </success_criteria>

<error_handling> Constitutional Conflicts: When principles conflict (e.g., "Move Fast" vs "High Quality"):

Option 1 - Hierarchy: Explicitly rank principles

### Principle Hierarchy

When principles conflict, apply in this order:
1. Security (never compromised)
2. User Privacy
3. Reliability
4. Simplicity
5. Speed of iteration

Option 2 - Rewrite: Eliminate conflict by rewriting both

**Before**:
- Move fast and ship features quickly
- Maintain high code quality always

**After**:
- Ship fast with tech debt, pay it down when velocity slows
- Quality in external APIs and data models, pragmatic in internals

</error_handling>

References

For detailed information, see:

• references/detailed-guide.md - Complete workflow details, examples, and troubleshooting