Skill: aposd-maintaining-design-quality

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