---
description: Define design principles and governance rules for the domain specification
---

## User Input

```text
$ARGUMENTS
```

You **MUST** consider the user input before proceeding (if not empty).

## Outline

You are updating **Part II: Specification Design Principles** in `/memory/constitution.md`. This section defines guidelines for defining domain specifications (entities, validation rules, operations).

Unlike toolkit implementation principles (Part III), Part II focuses on **specification quality** - it guides decisions about entity definitions, validation rules, operation interfaces, and error handling specifications.

Follow this execution flow:

### 1. Load existing constitution

- Read `/memory/constitution.md`
- Locate `## Part II: Specification Design Principles` section
- Preserve Part I and Part III unchanged

### 2. Understand the domain specification

**Critical**: Before updating principles, understand what specifications this toolkit defines:
- What domain does this serve? (Marketing, MCP, API Testing?)
- What entities are specified? (Campaign, Tool, APITest?)
- What validation rules are needed? (Budget constraints, Schema validation?)
- What operations are defined? (CRUD, Events, Commands?)

**Ask clarifying questions if unclear**:
- "What domain specifications does this toolkit support?"
- "What are the core entities in domain specifications?"
- "What validation rules should specifications enforce?"

### 3. Update Part II principles

Based on user input and domain understanding, update these **standard specification design principles** in Part II:

#### **I. Entity Clarity**
- Entity definitions are complete and unambiguous
- All fields have explicit types and descriptions
- Required vs optional clearly specified
- Examples provided for every entity

**Rationale**: Clear entities enable consistent implementations across different tools.

#### **II. Validation Completeness**
- All constraints explicitly documented
- Error conditions clearly specified
- Edge cases addressed
- Validation rules traceable to domain requirements

**Rationale**: Complete validation specs prevent implementation divergence.

#### **III. Operation Semantics**
- All operations have clear purposes
- Request/response schemas fully specified
- Side effects documented
- Idempotency requirements stated

**Rationale**: Well-defined operations enable interoperable implementations.

#### **IV. Implementation Neutrality**
- Specification doesn't mandate specific technologies
- Focuses on WHAT, not HOW
- Platform-agnostic specifications
- Multiple implementations possible

**Rationale**: Technology-neutral specifications have longer lifespans and wider adoption.

#### **V. Extensibility Design**
- Extension points clearly marked
- Backward compatibility rules defined
- Versioning strategy specified
- Deprecation process documented

**Rationale**: Specifications must evolve without breaking existing implementations.

#### **VI. Domain Fidelity**
- Respects domain standards and conventions
- References authoritative sources (RFCs, W3C, etc.)
- Domain terminology consistently used
- Domain constraints explicitly stated

**Rationale**: Domain-faithful specifications are easier to adopt and understand.

### 4. Prepare domain-specific examples

For each principle in Part II, provide domain-specific examples:

- **Entity Clarity**: What entities? What fields? Types?
- **Validation Completeness**: What validation rules? Constraints?
- **Operation Semantics**: What operations? Inputs/outputs?
- **Implementation Neutrality**: How to avoid technology coupling?
- **Extensibility Design**: How to support evolution?
- **Domain Fidelity**: What standards to follow? Terminology?

**Examples by domain**:
- Marketing: Campaign (name, type, channels, budget, dates), CPM/CTR/ROAS validation
- MCP: Tool (name, description, inputSchema), JSON Schema validation
- API Testing: APITest (endpoint, method, assertions), HTTP status validation

### 5. Update Part II section

Update only the `## Part II: Specification Design Principles` section with domain-specific content:

```markdown
## Part II: Specification Design Principles

**Purpose**: Guidelines for defining {domain} specifications (entities, validation rules, operations)

### 1. Entity Clarity

[Domain-specific entity examples and rules]

### 2. Validation Completeness

[Domain-specific validation rules]

### 3. Operation Semantics

[Domain-specific operations]

### 4. Implementation Neutrality

{How to keep specs technology-neutral}

### 5. Extensibility Design

[Evolution and versioning strategy]

### 6. Domain Fidelity

[Domain standards and conventions to follow]

<!-- Managed by /metaspec.sds.constitution -->
```

**CRITICAL**: Only update Part II. Preserve Part I and Part III exactly as they are.

### 6. Consistency propagation and impact analysis

Check and update dependent files to align with updated principles:

#### A. Domain Specifications
- **Read** `/specs/domain/001-*/spec.md` (if exists)
- **Check** entity definitions match Entity Clarity principle
- **Check** validation rules match Validation Completeness principle
- **Check** operations match Operation Semantics principle
- **Note** any inconsistencies

#### B. MetaSpec Commands
- **Read** `/.metaspec/commands/sds.specify.md` (if exists)
- **Check** if principles are referenced in guidance
- **Update** if principle names or descriptions changed
- **Mark** with `<!-- Updated per constitution v{VERSION} -->`

#### C. Specification Templates
- **Read** `/src/metaspec/templates/meta/templates/domain-spec-template.md.j2` (if exists)
- **Check** template structure matches required principles
- **Check** mandatory sections align with Entity Clarity and Validation Completeness
- **Update** if new principles require new sections

#### D. Project Documentation
- **Read** `/README.md`
- **Check** "Specification Design" or similar sections
- **Update** if principles changed
- **Read** `/AGENTS.md`
- **Check** Part II references in Constitutional Principles section
- **Update** if principle names changed

#### E. Example Specifications
- **Read** `/examples/*/spec.md` (if exists)
- **Check** if examples follow updated principles
- **Note** examples that need updating

**Track all changes**:
- ✅ Updated: List files successfully updated
- ⚠️ Needs manual review: List files requiring human attention
- 📝 Recommendations: Suggest improvements to specs/docs

### 7. Generate detailed Sync Impact Report

Prepend this as an HTML comment at the top of `/memory/constitution.md`:

```html
<!--
Constitution Part II Update Report
===================================
Version: {OLD_VERSION} → {NEW_VERSION} ({BUMP_TYPE})
Updated: {ISO_DATE}
Rationale: {Brief reason for update}

Key Changes:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
{IF modified}: • Modified: {PRINCIPLE_NAME} - {brief change}
{IF added}: • Added: {NEW_PRINCIPLE_NAME} - {brief description}
{IF removed}: • Removed: {OLD_PRINCIPLE_NAME} - {reason}

Impact:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Updated: {count} files (specs/commands/docs)
Review: {count} files may need manual updates
Constitution Compliance: {✅ Maintained | ⚠️ Check required}

Follow-up: Review existing specs, update examples, validate compliance

Generated by: /metaspec.sds.constitution
-->
```

### 8. Update version and timestamp

Update the version line at the top of `/memory/constitution.md`:

```markdown
> Version {NEW_VERSION} | Ratified: {ORIGINAL_DATE} | Last Updated: {TODAY}
```

**Version bump rules** (CRITICAL):

**MAJOR (X.0.0)** - Part I changes only:
- Core values modified or removed
- Project philosophy fundamentally changed
- Breaking changes to constitutional framework
- Example: 1.0.0 → 2.0.0

**MINOR (X.Y.0)** - Part II or Part III changes:
- New principles added to Part II
- Existing principles significantly expanded
- New mandatory sections or requirements
- Principle renamed (semantic change)
- Example: 1.1.0 → 1.2.0

**PATCH (X.Y.Z)** - Minor refinements:
- Clarifications, wording improvements
- Examples added to existing principles
- Typo corrections
- Non-semantic formatting changes
- Example: 1.1.0 → 1.1.1

**For Part II updates**:
- If principles added/removed: MINOR bump
- If principles substantially changed: MINOR bump
- If only examples/clarifications added: PATCH bump
- If domain-specific rules added: MINOR bump

**Add update marker in Part II**:
```markdown
<!-- Managed by /metaspec.sds.constitution -->
<!-- Last updated: {TODAY} v{VERSION} - {Brief description of changes} -->
```

### 9. Validation checklist

Before writing file, verify:

**Critical Checks**:
- [ ] Part I/III unchanged, Part II updated
- [ ] All 6 specification design principles present in Part II
- [ ] Version bump follows semantic versioning (MAJOR: Part I, MINOR: Part II/III, PATCH: fixes)
- [ ] Impact Report prepended at top
- [ ] Version line updated: `> Version X.Y.Z | Ratified: ... | Last Updated: ...`

**Quality Checks**:
- [ ] Each principle has domain-specific examples
- [ ] Consistency check results documented
- [ ] Affected files listed in Impact Report

### 10. Write updated constitution

**Write order**:
1. **Prepend** HTML comment Sync Impact Report at top
2. **Preserve** Part I exactly (Project Core Values)
3. **Update** Part II (Specification Design Principles)
4. **Preserve** Part III exactly (Toolkit Implementation Principles)
5. **Preserve** Governance section at bottom

**Write to**: `/memory/constitution.md`

**Quality checks**:
- Proper Markdown formatting
- Single blank line between sections
- No trailing whitespace
- Consistent heading levels

### 11. Output summary to user

Provide a comprehensive summary:

```
✅ Constitution Part II (Specification Design) updated to v{NEW_VERSION}

📊 Version Change: v{OLD_VERSION} → v{NEW_VERSION}
Bump Type: {MAJOR|MINOR|PATCH}
Rationale: {Brief reason for version bump}

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📋 Changes in Part II:
Modified Principles:
- {PRINCIPLE_NAME}: {What changed}

Added Principles:
- {NEW_PRINCIPLE_NAME}: {Brief description}

Removed Principles:
- [OLD_PRINCIPLE_NAME]: [Reason for removal]

Domain-Specific Updates:
- [DOMAIN]: {What was added/changed}

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📁 Files Updated:
✅ Successfully Updated:
- /memory/constitution.md (Part II)
- [List other files auto-updated]

⚠️  Require Manual Review:
- [List files needing human attention]

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✅ Consistency Check Results:
- Domain specifications reviewed: [COUNT]
- Specifications compliant: [COUNT]
- Specifications needing update: [COUNT]
- Documentation files checked: [COUNT]

📋 Follow-up TODOs:
- [ ] [TODO item 1]
- [ ] [TODO item 2]
- [ ] [TODO item 3]

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🔄 Next Steps:
1. Review the Sync Impact Report in /memory/constitution.md (HTML comment at top)
2. Review Part II changes in /memory/constitution.md
3. Address files marked ⚠️  Require Manual Review
4. Use /metaspec.sds.specify to define specifications following updated principles
5. Use /metaspec.sds.checklist to validate existing specifications

💡 Suggested Commit Message:
   docs(constitution): update Part II to v{NEW_VERSION} ({brief description})
   
   - {Change 1}
   - {Change 2}
   
   Affects: {list key files}
```

## Important Notes

1. **Constitution is for the specification, not implementations**
   - This defines how to SPECIFY the specification
   - It does NOT define how to IMPLEMENT the specification
   - Focus on entity definitions, validation rules, operation interfaces

2. **Standard vs Domain-Specific Principles**
   - Always include the 6 standard specification design principles
   - Add domain-specific principles as needed (e.g., "RESTful Conventions" for APIs)
   - Don't remove standard principles without strong justification

3. **Examples Matter**
   - Each principle should include specification-specific examples
   - Examples should use the actual entities from this specification
   - Bad: "Entities should be clear"
   - Good: "Entity `Tool` must specify `name` (string, required), `description` (string, required), `inputSchema` (JSON Schema, required)"

4. **Specification-First Language**
   - Write for specification designers reading this document
   - Use imperative language (MUST, SHOULD, MAY)
   - Avoid ambiguity ("usually", "typically" → specify exact rules)
   - Include anti-patterns (what NOT to specify)

5. **Version Control**
   - Never decrement version
   - Document reason for every version bump
   - Keep sync report for traceability

