/what-would-break

Using @agent-mentor investigate what would be affected by a proposed change, teaching impact analysis and systems thinking through comprehensive dependency mapping and risk assessment.

Input Parsing

The user invoked: /what-would-break {proposed_change}

Examples:

• /what-would-break if we change the User model schema - Data model changes
• /what-would-break removing the cache layer - Architectural changes
• /what-would-break changing this function signature - API changes
• /what-would-break upgrading React to v19 - Dependency upgrades
• /what-would-break - Interactive mode to discuss potential changes

Your Task

This is an educational investigation designed to teach impact analysis, not to discourage changes. The goal is to help developers build the mental models that senior engineers use to reason about system dependencies, ripple effects, and change management.

Core Philosophy

We are teaching, not gatekeeping. Every finding should help the developer understand:

• How things are connected (system architecture)
• Why they're connected (design patterns and dependencies)
• What to watch for when making changes (testing strategies)
• How to mitigate risks (safe change patterns)

This tool should empower developers to make changes confidently, not frighten them away from necessary work.

1. Change Specification

Clarify what's being considered:

• What exactly would change? (Code, API, data structure, dependency)
• What's the motivation? (Bug fix, performance, refactor, feature)
• What's the scope? (Function, module, system-wide)
• What's the timeline? (Exploration, planning, imminent)

If unclear, ask:

• "What specific change are you considering?"
• "Is this a signature change, behavior change, or removal?"
• "Are you exploring options or planning implementation?"
• "What problem are you trying to solve?"

2. Dependency Analysis

Map the complete dependency graph:

Direct Dependencies (First-Order Effects)

Code Dependencies:

# Find all imports/requires of this module
grep -r "import.*from.*{module}" .
grep -r "require.*{module}" .

# Find all references to this function/class
grep -r "{identifier}" . --include="*.ts" --include="*.js"

# Use language-specific tools
# TypeScript: Check with tsc --noEmit and language server
# Python: Use AST analysis
# Go: Use go list -json

Data Dependencies:

• What reads this data structure?
• What writes to it?
• What transforms or validates it?
• What stores or caches it?

API Dependencies:

• What calls this endpoint?
• What consumers depend on this response shape?
• What clients (web, mobile, third-party) use this?
• What integrations rely on this behavior?

Indirect Dependencies (Second-Order Effects)

Cascading Changes:

• What depends on the things that depend on this?
• What shared abstractions would need updating?
• What patterns or conventions would be affected?
• What documentation would be outdated?

Transitive Dependencies:

• What tests validate this behavior?
• What monitoring assumes this structure?
• What logs or debugging depend on this?
• What tooling or scripts rely on this?

Hidden Dependencies (Subtle Effects)

Timing Dependencies:

• Does anything assume performance characteristics?
• Are there race conditions that rely on current timing?
• Do caches depend on update patterns?

State Dependencies:

• What assumes initialization order?
• What relies on side effects?
• What expects specific error states?

Environmental Dependencies:

• Do different environments behave differently?
• Are there feature flags involved?
• Do deployment configurations matter?

3. Impact Assessment

For each affected area, analyze:

Severity Levels

Critical (System Breaking):

• Production outages
• Data corruption or loss
• Security vulnerabilities
• Revenue-impacting failures
• Customer-facing errors

High (Feature Breaking):

• Feature completely non-functional
• Major workflows blocked
• Performance degradation >50%
• User-visible errors

Medium (Partial Impact):

• Graceful degradation
• Edge cases broken
• Non-critical features affected
• Internal tools impacted

Low (Minimal Impact):

• Logging or monitoring gaps
• Documentation outdated
• Internal refactor needed
• Test updates required

Probability Assessment

Certain (Will Break):

• Direct API contract violations
• Type mismatches
• Compilation errors
• Known dependency violations

Likely (Probably Breaks):

• Runtime behavior changes
• Assumption violations
• Performance degradation
• State management issues

Possible (Might Break):

• Edge cases
• Race conditions
• Environment-specific issues
• Subtle behavior changes

Unlikely (Edge Cases):

• Obscure scenarios
• Deprecated code paths
• Legacy fallbacks

4. Test Coverage Analysis

Map what tests protect against breakage:

Unit Tests:

• What tests directly cover this code?
• What tests would catch interface changes?
• Are there tests for edge cases?

Integration Tests:

• What tests validate interactions?
• Do tests cover the dependency chain?
• Are integration points tested?

End-to-End Tests:

• What user flows exercise this code?
• Do E2E tests cover critical paths?
• Are there smoke tests?

Test Gaps:

• What isn't tested?
• Where are we relying on luck?
• What should we add before changing?

5. Change Mitigation Strategies

Teach safe change patterns:

Incremental Rollout:

• Feature flags
• Gradual percentage rollout
• Canary deployments
• Shadow mode (run both, compare results)

Backwards Compatibility:

• Deprecation periods
• Adapter patterns
• Version negotiation
• Graceful fallbacks

Validation Strategies:

• Pre-deployment testing
• Monitoring and alerting
• Rollback plans
• Data validation

Communication Plans:

• Who needs to know?
• What documentation updates?
• API changelog entries
• Team notifications

6. Save Output

Create a markdown file at /reports/what-would-break-{change}-{timestamp}.md with the blast radius analysis.

Output Format

# Blast Radius Analysis: [Change Description]

## The Proposed Change
**What**: [Specific change being considered]
**Why**: [Motivation for the change]
**Scope**: [How much would change]
**Status**: [Exploration / Planning / Ready to implement]

## Executive Summary
[2-3 sentence overview of impact and risk level]

**Overall Risk Level**: 🔴 High / 🟡 Medium / 🟢 Low
**Affected Systems**: [Count and list]
**Required Test Updates**: [Count]
**Estimated Effort**: [T-shirt size or time estimate]

---

## Dependency Map

### Direct Dependencies (First-Order Effects)
[Things that immediately depend on what's changing]

#### Code References
**Files that import/use this code:** [Count]

- `src/services/auth.ts` - Uses `validateUser()` function
  - **Impact**: Would need signature update
  - **Lines**: 45, 67, 123
  - **Severity**: 🔴 Critical - Auth would break

- `src/controllers/user.ts` - Calls this API
  - **Impact**: Response shape change needed
  - **Lines**: 89-92
  - **Severity**: 🟡 Medium - Needs adapter

[Continue for all direct dependencies...]

#### Data Consumers
**Components reading/writing this data:** [Count]

- Database migrations
  - **Impact**: Schema migration required
  - **Risk**: 🔴 Data consistency issues

- Cache layer
  - **Impact**: Cache invalidation needed
  - **Risk**: 🟡 Stale data during transition

#### API Consumers
**External/internal API consumers:** [Count]

- Mobile app (iOS/Android)
  - **Impact**: App update required
  - **Risk**: 🔴 Version compatibility issues
  - **Mitigation**: Support both formats during transition

- Third-party integrations
  - **Impact**: Partner notification required
  - **Risk**: 🟡 Partner systems may break

### Indirect Dependencies (Second-Order Effects)
[Things that depend on the things that depend on this]

#### Cascading Code Changes

- `src/services/notifications.ts` depends on `auth.ts`
  - **Why it matters**: Auth changes propagate to notifications
  - **What breaks**: User notification context
  - **Learning**: Shared abstractions amplify changes

#### Transitive System Effects

- Monitoring dashboards
  - **Why it matters**: Metrics rely on current data shape
  - **What breaks**: Dashboard queries, alerts
  - **Learning**: Observability is a dependency too

- Logging pipelines
  - **Why it matters**: Log parsing expects current format
  - **What breaks**: Log aggregation, debugging
  - **Learning**: Developer tools depend on stability

### Hidden Dependencies (Subtle Effects)
[Non-obvious things that could break]

#### Performance Assumptions

- `src/cache/strategy.ts` assumes query takes <100ms
  - **Why it matters**: Cache TTL tuned to current performance
  - **What might break**: Cache hit rate drops
  - **Learning**: Performance characteristics are implicit contracts

#### Timing and Race Conditions

- Event handlers expect current ordering
  - **Why it matters**: State synchronization relies on order
  - **What might break**: Race conditions emerge
  - **Learning**: Temporal dependencies are often undocumented

#### Environmental Variations

- Production uses different DB version than dev
  - **Why it matters**: SQL compatibility varies
  - **What might break**: Works in dev, fails in prod
  - **Learning**: Environment parity gaps create hidden risks

---

## Impact Assessment

### By Severity

#### 🔴 Critical Impacts (System Breaking)
[Changes that would cause outages or data loss]

1. **Authentication System Failure**
   - **What breaks**: All authenticated endpoints
   - **User impact**: Cannot log in
   - **Revenue impact**: Complete service outage
   - **Probability**: Certain (will break without updates)
   - **Affected users**: All users

   **Why this is critical:**
   The auth system has no fallback. This is a single point of failure.

   **What to do first:**
   - Add comprehensive integration tests
   - Plan staged rollout
   - Prepare immediate rollback procedure

2. **Data Corruption Risk**
   - **What breaks**: User profile data structure
   - **User impact**: Data loss or corruption
   - **Probability**: Likely (without migration)

   **Why this is critical:**
   Schema mismatch between old and new format could corrupt records.

   **What to do first:**
   - Write migration with rollback
   - Test on production data snapshot
   - Add data validation checks

#### 🟡 Medium Impacts (Feature Breaking)
[Changes that break features but not the whole system]

1. **User Profile Page Errors**
   - **What breaks**: Profile rendering
   - **User impact**: 500 errors on profile page
   - **Probability**: Certain (field names change)
   - **Workaround**: Falls back to default profile

   **Why this matters:**
   Degrades UX but doesn't block core workflows.

   **What to do:**
   - Update React components
   - Add PropTypes validation
   - Test profile edge cases

#### 🟢 Low Impacts (Minor Issues)
[Changes that need attention but aren't urgent]

1. **Internal Dashboard Metrics**
   - **What breaks**: Admin dashboard charts
   - **User impact**: Internal users only
   - **Probability**: Certain (metric names change)

   **Why this matters:**
   Internal tooling, not customer-facing.

   **What to do:**
   - Update dashboard queries
   - Document metric changes

### By Subsystem

#### Frontend Impact
**Affected Components**: [Count]
**Severity**: 🟡 Medium

- User profile components need updates
- Form validation logic changes
- API client needs new types

**Teaching moment:** Frontend changes ripple through component trees.

#### Backend Impact
**Affected Services**: [Count]
**Severity**: 🔴 High

- Auth service core change
- Database schema migration
- API versioning required

**Teaching moment:** Backend changes affect contracts with all clients.

#### Database Impact
**Tables Affected**: [Count]
**Severity**: 🔴 Critical

- Migration required
- Downtime possible
- Rollback complexity high

**Teaching moment:** Data migrations are high-risk and need thorough planning.

#### Infrastructure Impact
**Systems Affected**: [Count]
**Severity**: 🟢 Low

- Cache invalidation needed
- CDN purge required
- Monitoring updates

**Teaching moment:** Don't forget infrastructure dependencies.

---

## Test Coverage Analysis

### Existing Test Protection

#### ✅ Well-Covered Areas
[Tests that would catch breakage]

- **Unit Tests**: `auth.test.ts`
  - Covers: Function signatures, basic behavior
  - **Would catch**: Interface changes
  - **Confidence**: High
  - Lines: 234 tests, 95% coverage

- **Integration Tests**: `auth-integration.test.ts`
  - Covers: Auth flow end-to-end
  - **Would catch**: Workflow breakage
  - **Confidence**: High

#### ⚠️ Partially Covered Areas
[Tests that might catch breakage]

- **E2E Tests**: Login flow tested
  - Covers: Happy path only
  - **Might catch**: Critical path breakage
  - **Might miss**: Edge cases, error states
  - **Gap**: No tests for failed auth scenarios

#### ❌ Uncovered Areas (Test Gaps)
[Areas with no test protection]

- **Missing Tests**: Token refresh flow
  - **Why it matters**: Could break silently
  - **Risk**: 🟡 Sessions expire unexpectedly
  - **Recommendation**: Add before making changes

- **Missing Tests**: Third-party OAuth
  - **Why it matters**: External integration
  - **Risk**: 🔴 Partner integrations break
  - **Recommendation**: Critical to test first

### What We're Relying on Luck For

**Untested assumptions:**
1. Database connection pooling handles new query patterns
   - **Why risky**: Could cause connection exhaustion
   - **How to test**: Load testing with new queries

2. Mobile apps handle API version correctly
   - **Why risky**: No automated tests for version negotiation
   - **How to test**: Manual testing on multiple app versions

**Teaching moment:** If there's no test, assume it will break. Add tests before changing.

---

## Safe Change Strategies

### Recommended Approach
[Best way to make this change safely]

**Strategy**: Expand-Contract Pattern (3-phase deployment)

**Phase 1: Expand (Add new without removing old)**
- Add new API endpoint alongside old
- Support both data formats
- Add feature flag for gradual rollout
- Deploy and monitor

**Phase 2: Migrate (Move clients to new)**
- Update frontend to new endpoint
- Migrate mobile apps (with backwards compat)
- Move internal services
- Monitor error rates closely

**Phase 3: Contract (Remove old)**
- Deprecate old endpoint (with warnings)
- Wait for client adoption
- Remove old code
- Clean up feature flags

**Teaching moment:** The safest way to change APIs is to run both versions simultaneously.

### Alternative Approaches

#### Option A: Big Bang Deployment
**Pros**: Faster, simpler code
**Cons**: High risk, all-or-nothing
**When to use**: Small changes with excellent test coverage
**Risk level**: 🔴 High

#### Option B: Shadow Mode
**Pros**: Test in production without risk
**Cons**: More complex, requires duplicate processing
**When to use**: High-risk changes, performance-critical code
**Risk level**: 🟢 Low

**Teaching moment:** Different situations call for different strategies.

### Rollout Plan

**Week 1: Preparation**
- [ ] Add missing tests (focus on critical paths)
- [ ] Set up feature flag
- [ ] Create monitoring dashboard
- [ ] Write rollback runbook
- [ ] Review with team

**Week 2: Deploy Phase 1 (Expand)**
- [ ] Deploy new code (behind feature flag)
- [ ] Enable for internal users only
- [ ] Monitor error rates, performance
- [ ] Fix any issues discovered

**Week 3: Deploy Phase 2 (Migrate)**
- [ ] Gradually increase feature flag % (10%, 25%, 50%, 100%)
- [ ] Monitor at each stage
- [ ] Update mobile apps
- [ ] Notify third-party partners

**Week 4: Deploy Phase 3 (Contract)**
- [ ] Mark old API as deprecated
- [ ] Wait 2 weeks for stragglers
- [ ] Remove old code
- [ ] Clean up feature flags

**Teaching moment:** Patient, incremental rollouts catch issues before they affect everyone.

### Monitoring and Alerts

**Critical Metrics to Watch:**

- **Error Rate**: Auth failures > 0.1%
  - **Alert threshold**: 0.5%
  - **Action**: Immediate rollback

- **Latency**: Login time > 500ms
  - **Alert threshold**: 1000ms
  - **Action**: Investigate before proceeding

- **Success Rate**: Login success < 99%
  - **Alert threshold**: < 98%
  - **Action**: Pause rollout

**Teaching moment:** You can't manage what you don't measure. Set up monitoring first.

### Rollback Plan

**Immediate Rollback Triggers:**
- Error rate > 1%
- Data corruption detected
- Security vulnerability discovered
- Critical partner integration breaks

**Rollback Procedure:**
```bash
# 1. Disable feature flag
curl -X POST api/flags/new-auth/disable

# 2. Revert deployment (if needed)
kubectl rollout undo deployment/auth-service

# 3. Verify rollback successful
curl api/health/auth

# 4. Notify team and stakeholders

Rollback Time: < 5 minutes Data Rollback: Migration has rollback script tested

Teaching moment: Always have a rollback plan before you need it.

---

Communication Plan

Who Needs to Know

Before Making Changes

• Backend team - Core change owners
• Frontend team - API contract changes
• Mobile team - App compatibility required
• QA team - Test plan review
• DevOps team - Deployment strategy
• Product team - User impact awareness

During Rollout

• On-call engineers - Monitoring responsibilities
• Support team - Potential user issues
• Partners - API changes affecting integrations

After Completion

• All engineers - Pattern changes, learnings
• Documentation team - Update API docs

Documentation Updates Required

• API documentation (swagger/openapi)
• Architecture decision record (ADR)
• Migration guide for API consumers
• Changelog entry
• Internal wiki update
• Code comments explaining new pattern

Teaching moment: Communication is part of the change, not an afterthought.

---

Learning Outcomes

Systems Thinking Lessons

About Dependencies:

• Direct dependencies are visible, indirect ones take investigation
• Every API is a contract that others depend on
• Data structures have consumers beyond obvious code
• Tests are dependencies too - they assume behavior

About Risk Management:

• Severity × Probability = Risk prioritization
• Test coverage directly reduces risk
• Incremental changes are safer than big bangs
• Monitoring is your safety net

About Change Management:

• Backwards compatibility buys safety
• Feature flags enable gradual rollout
• Communication prevents surprises
• Documentation captures decisions

Patterns to Recognize

High-Risk Change Patterns:

• Changes to shared abstractions (used everywhere)
• Data structure changes (hard to roll back)
• API contract changes (external dependencies)
• Performance-critical code (hard to predict)

Lower-Risk Change Patterns:

• Internal implementation changes (same interface)
• Additive changes (new features, not modifications)
• Well-tested code (safety net exists)
• Isolated modules (limited blast radius)

Teaching moment: With practice, you'll recognize high-risk patterns instantly.

Questions to Always Ask

Before making any change, ask yourself:

1. Who depends on this?

   • Direct callers, data consumers, API clients

2. What might break?

   • Obvious breaks, subtle breaks, edge cases

3. How will I know if it breaks?

   • Tests, monitoring, alerts, user reports

4. How can I make it safer?

   • Incremental rollout, feature flags, backward compatibility

5. What's my rollback plan?

   • How to undo, how long it takes, what data is affected

Teaching moment: Senior engineers ask these questions reflexively. Now you have the checklist.

---

Action Items

Before Starting Implementation

High Priority (Must Do):

• Add test coverage for [uncovered critical path]
• Set up monitoring for [key metric]
• Write migration rollback script
• Review plan with team

Medium Priority (Should Do):

• Document current behavior
• Create feature flag
• Set up staging environment test
• Draft API changelog

Low Priority (Nice to Have):

• Refactor related code
• Update tangential documentation
• Add additional logging

During Implementation

• Keep changes small and incremental
• Test each step before proceeding
• Monitor metrics continuously
• Document unexpected findings

After Completion

• Update all documentation
• Remove feature flags and dead code
• Share learnings with team
• Update this analysis if assumptions were wrong

---

Related Investigations

Want to Learn More?

• Why was it built this way? → Try /why-this-way [code]
• How does this work? → Try /explain [concept]
• How did this evolve? → Check git history with code-historian agent

Similar Changes to Study

[Link to other similar changes in the codebase]

• PR #234: Similar API change - learn from their approach
• Commit abc123: Previous schema migration - see how they did it
• Issue #456: Discussion of this pattern - context for decision

Teaching moment: Every change is a learning opportunity. Study both successes and failures.

---

Confidence Assessment

Analysis Completeness: High / Medium / Low Test Coverage Confidence: High / Medium / Low Risk Assessment Confidence: High / Medium / Low

Areas of Uncertainty: [Things we're not sure about]

• Third-party integration behavior - need to verify
• Production load characteristics - need metrics
• Legacy code paths - need archaeology

How to Improve Confidence:

1. [Specific action to reduce uncertainty]
2. [Where to get more information]
3. [Who to ask for domain knowledge]

---

Summary: Your Change Roadmap

The Change: [One sentence]

Risk Level: 🔴/🟡/🟢

Critical Dependencies: [Top 3]

Must-Have Tests: [Top 3 test gaps to fill]

Recommended Strategy: [Chosen approach]

Timeline: [Realistic estimate]

First Step: [Specific next action]

Teaching moment: You now understand the full impact. This is how senior engineers think about changes. You're ready to proceed safely.

---

Analysis completed: [timestamp] Files analyzed: [count] Dependencies mapped: [count] Tests reviewed: [count] Risk areas identified: [count]

Remember: This analysis is meant to empower you to make changes confidently, not to discourage necessary improvements. Every large system has complexity. With careful planning and incremental rollout, you can safely evolve even critical code.

## Investigation Techniques

### Dependency Discovery

**Static Analysis:**
```bash
# Find all imports
grep -r "import.*{identifier}" . --include="*.ts"

# Find all string references (for dynamic imports)
grep -r "{identifier}" . --include="*.ts" --include="*.js"

# Use AST tools for accurate analysis
npx ts-node -e "import * as ts from 'typescript'; /* analyze AST */"

# Language Server Protocol for IDE-quality analysis
# Better than grep for finding actual usages

Runtime Analysis:

# Find all calls in logs
grep "{function_name}" logs/production.log | wc -l

# Check monitoring for usage patterns
# Grafana, DataDog, etc. for API call volumes

# Review APM traces for call graphs
# See what actually calls what in production

Test Analysis:

# Find all tests that mention this code
grep -r "describe.*{module}" . --include="*.test.*"
grep -r "it.*{function}" . --include="*.test.*"
grep -r "expect.*{identifier}" . --include="*.test.*"

# Check test coverage reports
cat coverage/lcov-report/index.html | grep "{file}"

Documentation Search:

# Find docs that reference this
grep -r "{identifier}" docs/ README.md

# Check API docs
grep -r "{endpoint}" docs/api/

# Search wiki/confluence if available

Impact Estimation Techniques

Code Complexity:

• Cyclomatic complexity (higher = more risk)
• Lines of code affected
• Number of files touched
• Depth of dependency tree

Usage Metrics:

• API call volume (high traffic = high risk)
• Feature adoption (widely used = careful)
• Error rates (fragile = proceed carefully)
• User impact (revenue-critical = maximum care)

Historical Data:

# How often does this code change?
git log --oneline -- {file} | wc -l

# How many bugs were found here?
gh issue list --search "involves:{file} label:bug"

# Who knows this code?
git log --format="%an" -- {file} | sort | uniq -c | sort -rn

Risk Scoring

Combine factors for overall risk score:

Risk = Severity × Probability × Blast Radius

Where:

• Severity: 1 (low) to 5 (critical)
• Probability: 0.1 (unlikely) to 1.0 (certain)
• Blast Radius: Number of affected users/systems

Examples:

• Score < 5: 🟢 Low risk
• Score 5-15: 🟡 Medium risk
• Score > 15: 🔴 High risk

Educational Approach

Building Senior Engineer Intuition

What Senior Engineers Know (That We're Teaching):

1. Dependency Awareness

   • Code dependencies are obvious
   • Data dependencies require investigation
   • Hidden dependencies are discovered through experience
   • Teaching method: Show how to find each type

2. Risk Calibration

   • Some changes are genuinely low-risk
   • Some changes feel safe but are dangerous
   • Testing reduces risk dramatically
   • Teaching method: Show risk factors and mitigation

3. Incremental Thinking

   • Large changes should be broken down
   • Each step should be safely reversible
   • Gradual rollout catches issues early
   • Teaching method: Show specific rollout strategies

4. Systems Thinking

   • Everything connects to everything
   • Indirect effects often matter more than direct ones
   • Non-code systems (monitoring, docs) are dependencies too
   • Teaching method: Map the full system, not just code

Encouraging Growth, Not Fear

DO:

• Frame as "interesting challenges" not "blockers"
• Provide specific strategies to mitigate risks
• Celebrate thoughtful change planning
• Share stories of successful complex changes
• Point out what's actually lower risk than it seems

DON'T:

• Use fear-based language ("this will break everything")
• Present problems without solutions
• Make complexity seem insurmountable
• Discourage necessary refactoring
• Gatekeep behind "senior engineer approval"

Teaching Through Examples

Include real examples from the codebase:

## Historical Example: Similar Change

In PR #234, we made a similar change to the Payment API:

**What they did right:**
- Ran both versions simultaneously for 2 weeks
- Added comprehensive monitoring
- Had clear rollback plan

**What we learned:**
- Edge case appeared only at 50% rollout
- Monitoring caught it before major impact
- Rollback took 2 minutes

**Apply to your change:**
- Use the same expand-contract pattern
- Watch for similar edge cases in [area]
- Set up similar monitoring for [metric]

Progressive Disclosure

For Simple Changes:

## Quick Assessment: Low Risk ✅

This change:
- Only affects internal implementation
- Has excellent test coverage
- No external API changes
- Small blast radius

**Quick wins:**
- Add one integration test for [edge case]
- Monitor [metric] after deploy
- Can deploy directly to production

**You're good to go!** This is a textbook low-risk change.

For Complex Changes:

## In-Depth Analysis Required ⚠️

This change touches critical infrastructure. Let's map it carefully:

[Full detailed analysis follows...]

**Don't be intimidated!** With the right approach, this is totally manageable:
[Specific strategy...]

Response Templates

When Change is Low Risk

Great news! This is a relatively low-risk change. Here's why:

✅ Internal implementation only (no API changes)
✅ Good test coverage (85%)
✅ Small blast radius (3 files)
✅ Well-isolated module

**Quick action items:**
1. Add one test for [edge case]
2. Monitor [metric] after deploy
3. Deploy to staging first

[Create concise report]

**Teaching moment:** This is what a low-risk change looks like. Notice the small blast radius and good test coverage. You can move forward confidently!

When Change is Medium Risk

This change has moderate complexity and risk. Here's the full picture:

[Analyze dependencies and impact]

**Key risks:**
1. [Risk 1] - Mitigate with [strategy]
2. [Risk 2] - Mitigate with [strategy]

**Recommended approach:**
Use feature flag + gradual rollout [details]

[Create detailed report]

**Teaching moment:** Medium-risk changes are where careful planning pays off. With the right strategy, you can make this change safely.

When Change is High Risk

This is a high-impact change that touches critical infrastructure. Let's plan this carefully:

[Comprehensive analysis]

**Critical risks:**
1. [Risk 1] - Requires [mitigation]
2. [Risk 2] - Requires [mitigation]

**Recommended approach:**
Shadow mode deployment over 3 phases [details]

[Create comprehensive report with detailed rollout plan]

**Teaching moment:** High-risk changes aren't scary when you have a solid plan. The key is incremental rollout with excellent monitoring. I'll help you execute this safely.

When User is Overestimating Risk

I can see why this seems risky, but it's actually safer than it appears! Here's why:

**What makes it feel risky:**
- [Perception 1]
- [Perception 2]

**But actually:**
- ✅ [Mitigating factor 1]
- ✅ [Mitigating factor 2]
- ✅ [Mitigating factor 3]

**Real risk level:** 🟢 Low (not 🔴 high)

[Brief analysis showing actual low impact]

**Teaching moment:** Some changes feel scary but are actually safe. Learning to calibrate risk accurately comes with experience.

When User is Underestimating Risk

This seems simple on the surface, but let me show you some hidden dependencies:

[Reveal surprising impacts]

**Surprising findings:**
1. [Hidden dependency 1] - Here's why it matters
2. [Hidden dependency 2] - Here's the impact
3. [Hidden dependency 3] - Here's the risk

**Actual risk level:** 🟡 Medium (not 🟢 low)

**Good news:** Now that we know, we can plan appropriately:
[Mitigation strategies]

**Teaching moment:** This is exactly the kind of hidden complexity that senior engineers learn to look for. Now you know what to check for!

Important Guidelines

1. Empower, don't gatekeep - Help them make changes safely
2. Teach systems thinking - Show how everything connects
3. Provide specific strategies - Don't just identify risks
4. Calibrate risk accurately - Neither overstate nor understate
5. Share mental models - Explain how to think about complexity
6. Encourage questions - This should start conversations
7. Celebrate good planning - Reinforce careful change management

Remember: The goal is to build senior engineers, not to make junior engineers afraid to change code. Every analysis should leave them more confident and better equipped to reason about system complexity.

---

CRITICAL: Report Generation

YOU MUST CREATE THE REPORT FILE. This is not optional.

Final Steps (MANDATORY)

1. Create the report file using the Write tool at the specified path:

   • Path format: /reports/{command-name}-{scope}-{timestamp}.md
   • Use ISO timestamp format: YYYY-MM-DD-HHmmss
   • Example: /reports/architecture-review-entire-project-2025-10-14-143022.md

2. Fill in ALL sections of the report template

   • Do not leave placeholder text
   • Provide specific, actionable findings
   • Include file paths and line numbers where relevant

3. Confirm completion by telling the user:

   • "Report saved to: [full path]"
   • Brief summary of key findings
   • Next steps or how to use the report

Common Mistakes to Avoid

❌ DON'T: Just summarize findings in the chat ❌ DON'T: Say "I'll create a report" without actually doing it ❌ DON'T: Leave sections incomplete or with placeholders ❌ DON'T: Forget to use the Write tool

✅ DO: Always use the Write tool to create the markdown file ✅ DO: Fill in every section with real findings ✅ DO: Provide the full path to the user when done ✅ DO: Include actionable recommendations

Verification Checklist

Before responding to the user, verify:

• Report file created with Write tool
• All template sections filled in
• Specific findings with file references
• Actionable recommendations included
• Timestamp in filename
• Full path provided to user

Remember: The report is the primary deliverable. The chat summary is secondary.