/pragmatic-guard

name: pragmatic-guard
description: Enables and configures Pragmatic Guard Mode (YAGNI Enforcement) to prevent over-engineering. Use when the user requests "Enable pragmatic mode", "Turn on YAGNI enforcement", "Activate simplicity guard", "Challenge complexity", or similar phrases.
allowed-tools: Read,Edit
disable-model-invocation: true

Pragmatic Guard Mode

Enables and configures the Pragmatic Guard Mode to actively challenge over-engineering.

Process

1. Check Current Configuration

• Read `.architecture/config.yml` to check current settings
• If config.yml doesn't exist, offer to create it from `.architecture/templates/config.yml`
• Check if `pragmatic_mode.enabled` is true
• Note the intensity level (strict/balanced/lenient)
• Review exemption categories and triggers

2. Enable Pragmatic Mode (if requested)

If user wants to enable:

• If config.yml doesn't exist:

  cp .architecture/templates/config.yml .architecture/config.yml

• Set `pragmatic_mode.enabled: true`
• Confirm intensity level with user or use default (balanced)
• Create `.architecture/deferrals.md` from template if it doesn't exist:

  cp .architecture/templates/deferrals.md .architecture/deferrals.md

• Inform user about mode activation and current settings

3. Configure Intensity Level

Ask user which intensity they prefer if not specified:

**Strict Mode**:

• Challenges aggressively, requires strong justification for any complexity
• Questions every "should" and "could"
• Pushes for absolute minimal implementation
• Best for: New projects, MVPs, startups with limited resources

**Balanced Mode** (RECOMMENDED):

• Challenges thoughtfully, accepts justified complexity
• Seeks middle ground between simplicity and best practices
• Questions "should" but accepts reasonable "must"
• Best for: Most projects, growing teams, moderate complexity

**Lenient Mode**:

• Raises concerns without blocking
• Suggests simpler alternatives as options
• Focuses on major complexity additions only
• Best for: Established projects, teams with strong architecture practices

4. Configure Triggers (optional)

Ask if user wants to customize which situations trigger pragmatic analysis:

• New abstraction layers (interfaces, base classes, DI containers)
• New external dependencies (libraries, frameworks, services)
• New architectural patterns (repository, strategy, observer)
• Scope expansion beyond initial requirements
• Performance optimizations without evidence
• Test infrastructure upfront
• Flexibility/configurability additions

5. Configure Exemptions (optional)

Confirm exemption categories where best practices should be maintained:

• Security-critical features (always exempt by default)
• Data integrity (always exempt by default)
• Compliance requirements (always exempt by default)
• Accessibility (always exempt by default)

6. Understanding the Pragmatic Enforcer

Explain how the Pragmatic Enforcer will participate:

**In Architecture Reviews**:

• Reviews each architect's recommendations
• Applies necessity assessment (0-10 scoring)
• Applies complexity assessment (0-10 scoring)
• Proposes simpler alternatives
• Calculates pragmatic score (complexity/necessity ratio, target <1.5)

**In ADR Creation**:

• Challenges proposed decisions
• Questions whether complexity is justified by current needs
• Suggests phased approaches or deferrals
• Documents trigger conditions for deferred decisions

**Question Framework**:

• **Necessity**: "Do we need this right now?" "What breaks without it?"
• **Simplicity**: "What's the simplest thing that could work?"
• **Cost**: "What's the cost of implementing now vs waiting?"
• **Alternatives**: "What if we just...?" "Could we use existing tools?"
• **Best Practices**: "Does this best practice apply to our context?"

7. Deferrals Tracking

If `behavior.track_deferrals` is true:

• Maintain `.architecture/deferrals.md` with deferred decisions
• Include trigger conditions for each deferral
• Track when deferrals are implemented or remain deferred

8. Report to User

Pragmatic Guard Mode: [Enabled | Disabled]

Configuration:
- Intensity: [strict | balanced | lenient]
- Apply to: [List of phases where it applies]
- Deferrals tracking: [enabled | disabled]

Exemptions:
- Security-critical: [enabled | disabled]
- Data integrity: [enabled | disabled]
- Compliance: [enabled | disabled]
- Accessibility: [enabled | disabled]

Triggers:
[List of active triggers]

The Pragmatic Enforcer will now:
- Challenge recommendations from other architects
- Question complexity and abstractions
- Propose simpler alternatives
- Calculate pragmatic scores (target ratio <1.5)
- [If enabled] Track deferred decisions in .architecture/deferrals.md

Next Steps:
- Create an ADR: "Create ADR for [topic]" (will include pragmatic analysis)
- Start a review: "Start architecture review for [target]" (will include pragmatic challenges)
- Adjust settings: Edit .architecture/config.yml

When to Use Pragmatic Mode

**Enable for**:

• New projects or MVPs
• Teams prone to over-engineering
• Resource-constrained environments
• Learning environments (teaching YAGNI)
• Projects with tight deadlines

**Consider disabling for**:

• Mature systems with established patterns
• High-complexity domains requiring abstractions
• Teams already practicing strong YAGNI principles
• Projects with specific architectural requirements

Notes

• Pragmatic mode is about finding balance, not blocking progress
• The Pragmatic Enforcer's role is to question and challenge, not to veto
• Intensity level should match team maturity and project complexity
• Exemptions ensure critical areas maintain appropriate rigor
• Deferrals can always be implemented when triggered by actual needs