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

```markdown
# 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

```markdown
# 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