codenamev/ai-software-architect/pragmatic-guard

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:

``bash 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:

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