cc-os/plugins/cc-architect/references/tool-patterns/templates/impact-analysis-template.md

Impact Analysis Template

Use this template before making changes to document what will be affected. Impact analysis prevents accidental regressions by forcing explicit consideration of downstream effects.

How to Use

1. Complete this analysis before implementing changes
2. Review against invariants and golden examples
3. Get sign-off if impact is significant
4. Store with the change (commit message, PR description, or dedicated file)

Template

# Impact Analysis: [Brief description of change]

**Date:** YYYY-MM-DD
**Proposed By:** [Who]

## What Will Change

[Specific, observable differences after the change]

- [Change 1]
- [Change 2]

## What Could Degrade

[Potential negative effects - be honest about risks]

- [Risk 1]: [Likelihood and severity]
- [Risk 2]: [Likelihood and severity]

## Invariants Affected

| Invariant | Status | Notes |
|-----------|--------|-------|
| [Invariant text] | preserved / violated / modified | [Explanation] |

## Golden Examples Affected

| Example | Status | Notes |
|---------|--------|-------|
| [Example name] | passes / fails / needs update | [Explanation] |

## Recommendation

[ ] Proceed - changes are safe
[ ] Proceed with monitoring - watch for [specific signals]
[ ] Defer - needs [what's missing]
[ ] Reject - violates [what constraint]

**Rationale:** [Why this recommendation]

Field Definitions

What Will Change: Observable differences. Focus on behavior, not implementation. Users should be able to notice these changes.

What Could Degrade: Honest risk assessment. Include low-probability high-impact risks. "Nothing could go wrong" is almost never true.

Invariants Affected: Check each documented invariant. "Preserved" means behavior unchanged. "Modified" means the invariant itself needs updating (rare and significant).

Golden Examples Affected: Run each golden example mentally or actually. "Needs update" means the example is wrong, not the change.

Recommendation: Clear action with justification. Defer and Reject are valid outcomes - not every change should proceed.

Example: Filled-in Template

# Impact Analysis: Add caching to skill-architect subagent spawn

**Date:** 2026-01-20
**Proposed By:** Developer

## What Will Change

- Subagent instructions cached for 5 minutes after first read
- Subsequent skill creations in same session use cached instructions
- Cache invalidated on any file change in skill-architect directory

## What Could Degrade

- Stale instructions if files change during session: Low likelihood, medium severity
- Memory usage from cache: Low likelihood, low severity
- Debugging difficulty if cache behavior unexpected: Medium likelihood, low severity

## Invariants Affected

| Invariant | Status | Notes |
|-----------|--------|-------|
| Always uses subagent for creation work | preserved | Cache is for instructions, not execution |
| Never creates files without reading existing patterns | preserved | Patterns still read, just cached |
| Always runs description-architect for frontmatter | preserved | Unaffected |

## Golden Examples Affected

| Example | Status | Notes |
|---------|--------|-------|
| Simple skill creation | passes | Behavior identical, just faster on repeat |
| Error handling | passes | Errors still propagate correctly |

## Recommendation

[x] Proceed with monitoring - watch for stale instruction complaints

**Rationale:** Performance improvement with low risk. Cache invalidation on file change handles the main failure mode. Monitor for user reports of unexpected behavior in first week.

When to Create Impact Analysis

Always create for:

• Changes to documented invariants
• Changes affecting multiple tools
• Performance optimizations (often have subtle behavior changes)
• Removing or deprecating features

Consider creating for:

• Adding new features (may affect existing behavior)
• Refactoring (should be behavior-preserving but verify)
• Dependency updates

Skip for:

• Documentation-only changes
• Adding tests without behavior changes
• Fixing bugs to match documented behavior

Using Impact Analysis Results

• Proceed: Implement, commit, done
• Proceed with monitoring: Implement, set reminder to check signals, document what to watch
• Defer: Document what's needed, create task to revisit
• Reject: Document in decision record why this change was rejected