architecture-workshop

This skill provides a framework for designing options when changes don't fit cleanly into existing codebase architecture.

When to Use

Load this skill when architecture fit evaluation returns NO_FIT or when you're compensating for architectural gaps with workarounds.

Core Principle

Your job is NOT to find workarounds that force a fit. If the right answer requires new architectural mechanisms, say so — even if a hacky fit is technically possible.

At the same time, don't over-engineer. If a light-touch structural improvement solves the problem cleanly, that's often better than a full architectural shift.

Process

1. Understand Why It Doesn't Fit

• Why doesn't this fit cleanly?
• Is it a localized mismatch or a systemic gap?
• What's the actual constraint violation vs. what's just unfamiliar?

2. Research Deeper (if needed)

Use the research skill to understand:

• What patterns exist for the type of problem this change introduces?
• Are there any partial implementations or footholds for the needed mechanism?
• What would be the natural extension points?

3. Generate Options

Light-Touch Options (consider first):

• Add a new module boundary + interface seam
• Introduce an adapter layer in one location
• Extract a small abstraction that makes the fit clean
• Add migration guardrails for incremental adoption

Architecture Options (when light-touch won't work):

• Introduce eventing/pubsub where none exists
• Add state-machine-driven workflow
• Change concurrency model
• Introduce new infrastructure component

4. Evaluate Each Option

For each option, assess:

• Blast radius: Which domains/components change (not individual files)
• Incremental path: Can we keep repo green throughout?
• Long-term impact: How this affects future changes, maintainability
• Reversibility: How hard to undo if wrong?

When to Recommend Light-Touch vs Architecture Shift

Light-Touch is right when:

• The problem is localized to 1-2 domains
• An interface seam or adapter solves it cleanly
• The repo already has similar patterns elsewhere
• Future changes won't keep hitting this same wall

Architecture Shift is right when:

• Multiple modules need to participate in a new coordination model
• The same problem will recur for future features
• The light-touch path creates inconsistent patterns
• The change represents a genuine evolution in what the system does

Output Format

Document your options:

## Architecture Options

### Option A: <Name>

- **Description**: <What this entails — stay high-level>
- **Blast Radius**: <Which domains/components change>
- **Incremental Path**: <Phases to adopt while keeping repo green>
- **Long-Term Impact**: <How this affects future changes>
- **Tradeoffs**: <Honest pros and cons>

### Option B: <Name>

<Same structure>

### Option C: <Name> (if meaningfully different)

<Same structure>

### Recommendation

<Which option and why — optimize for codebase health, not just "easiest fit">

Design Principles

• Codebase health is the objective: Don't contort just to fit
• Light-touch is often best: A well-placed interface seam can solve many problems
• Incremental path is mandatory: "Big bang" is not acceptable
• Blast radius matters: Prefer smaller when it solves the problem equally well
• Keep it high-level: Architectural guidance, not implementation planning
• Ground everything in repo reality: Options must be grounded in what actually exists