name: aposd-maintaining-design-quality
description: "Enforce strategic programming discipline when modifying existing code. Guide through STOP-ASK-DECIDE-VERIFY workflow with urgency tier assessment (trivial/minor/standard/emergency). Include when NOT to refactor (Chesterton's Fence, performance-critical, no tests) and block tactical shortcuts via anti-rationalization tables. Use when fixing bugs, extending features, or tempted to make quick fixes. Triggers on: modify code, fix bug, extend feature, quick fix, tactical change."

Skill: aposd-maintaining-design-quality

STOP - The Design Rule

If you're not making the design better, you're probably making it worse. Working code is not a high enough standard.

Zero Tolerance: There is no acceptable threshold for making design worse. Even "small" compromises accumulate invisibly—dozens of tactical decisions compound into unmaintainable systems.

Urgency Tiers

Not all changes need equal analysis. Match effort to impact:

Strategic Modification Workflow

BEFORE making any change to existing code:

1. RESIST the temptation to make a quick fix

2. ASK: "Is the current system design still the best one,
   given the change I need to make?"

3. IF NO: Refactor so you end up with the best possible design
   Goal: After this change, the system should have the structure
   it would have had if designed from the start with this in mind

4. IF YES: Make the change within the existing design
   But verify: does your change fit cleanly?

5. BEFORE COMMIT: Scan all changes to verify documentation reflects them

The Investment Mindset

Recommended investment: About 10-20% of development time on design improvements.

Why Strategic Wins

Tactical path:
- Each "quick fix" adds small complexity
- Complexities accumulate (dozens/hundreds of small things)
- Eventually: system is hard to understand and modify
- Result: development slows permanently

Strategic path:
- Each change improves or maintains design
- Past investments save time for future investments
- Eventually: strategic investments become FREE
- Result: development accelerates over time

Design Evolution Principle

A system's design cannot be conceived correctly at the outset. The design of a mature system is determined more by changes made during evolution than by initial conception.

Implication: Every modification matters. Your changes ARE the design.

When Refactoring Seems Impractical

Even under tight deadlines, ask:

"Is this the best I can possibly do to create a clean system design,
given my current constraints?"

Never acceptable: Making the design worse without a plan to fix it.

Accountability for Deferred Refactoring

If you defer refactoring, it MUST be tracked:

1. CREATE a ticket/issue with specific scope
2. TIMEBOX: Must be addressed within 2 sprints (or equivalent)
3. ADD a code comment: // TODO(YYYY-MM-DD): [ticket-id] - [what needs fixing]
4. ESCALATE if 3+ deferrals exist in same area → refactoring becomes MANDATORY

"I'll do it later" without these steps = you won't do it.

When NOT to Refactor

Refactoring is not always the right choice:

Key question: Do I understand WHY the code is the way it is?

Emergency Bypass Criteria

Skip the normal workflow ONLY when ALL of these conditions are true:

1. Production is down RIGHT NOW (not "might break soon")
2. Users are actively impacted, security breach in progress, OR data loss occurring
3. The fix is minimal (rollback or single-line change)
4. You commit to returning for proper implementation within 24 hours

Emergency does NOT mean:
- "Demo in 30 minutes" — That's planning failure
- "CEO is asking" — Authority pressure ≠ emergency
- "Team is blocked" — They can wait for you to think
- "We need this fast" — Speed pressure is when discipline matters MOST

Red Flags

Anti-Rationalization Table

Classic Rationalizations

Responsibility-Avoidance Rationalizations

"It Doesn't Count" Rationalizations

Comment Maintenance

When modifying code, keep comments synchronized:

Technical Debt Reality

Quick Reference

EVERY TIME you modify existing code:

1. STOP - Resist the quick fix temptation
2. ASK - "Is this design still optimal for what I need?"
3. DECIDE:
   - Design is optimal? Make change cleanly
   - Design needs work? Refactor first
   - Can't refactor now? Plan when you will
4. VERIFY - Comments updated? Design improved or maintained?
5. COMMIT - Only when design is better or at least not worse

THE RULE:
"If you're not making the design better, you're probably making it worse."

INVESTMENT MATH:
- 10-20% slower now → faster forever
- "Quick fix" now → 20%+ slower forever

Chain