Library Extraction Stabilisation

Library Extraction Stabilisation

Overview

Extract shared code into libraries only after proven stability and with clear ownership. Prevent premature abstraction, version chaos, and orphaned libraries.

REQUIRED: superpowers:brainstorming (before extraction decision)

When to Use

• Shared functionality used by 3+ components
• User asks "should I extract this as a library?"
• Code duplication across services/components
• User proposes creating shared package/library
• Existing internal library needs stabilization

Core Workflow

1. Count consumers (need 3+ for extraction)
2. Assess stability (change frequency over 3 months)
3. Define ownership (team with capacity)
4. Define versioning (SemVer, breaking change policy)
5. Plan migration (incremental, rollback strategy)
6. If not ready: Document alternative and re-evaluation criteria

Extraction Readiness Criteria

Red Flags - STOP

• "Already used in 2 places, should extract"
• "Keep changing in multiple places, must extract"
• "DRY principle requires extraction"
• "Library will force stability"

All mean: Apply readiness assessment before proceeding.

Rationalizations Table

Reference Documents

• Governance Models - Ownership and support models
• Versioning Strategy - SemVer, breaking changes
• Migration Planning - Consumer migration guide

Decision Matrix Template

Use this matrix to evaluate whether extraction is appropriate:

# Library Extraction Decision: [Component Name]

**Date**: YYYY-MM-DD
**Evaluator**: [Name]

## Readiness Assessment

| Criterion                        | Current State              | Threshold  | Pass? |
| -------------------------------- | -------------------------- | ---------- | ----- |
| Consumer count                   | [N]                        | ≥ 3        | ☐     |
| Change frequency (last 3 months) | [N/month]                  | < 2/month  | ☐     |
| Defined owner                    | [Team/None]                | Named team | ☐     |
| Support model                    | [SLA/Best-effort/None]     | Defined    | ☐     |
| API stability                    | [Stable/Evolving/Volatile] | Stable     | ☐     |
| Test coverage                    | [N]%                       | ≥ 80%      | ☐     |

## Consumer Analysis

| Consumer  | Integration Type  | Impact if Breaking Change |
| --------- | ----------------- | ------------------------- |
| Service A | Direct dependency | High - core functionality |
| Service B | Transitive        | Medium - feature subset   |
| Service C | Direct dependency | High - multiple endpoints |

## Risk Assessment

| Risk                              | Likelihood | Impact  | Mitigation                              |
| --------------------------------- | ---------- | ------- | --------------------------------------- |
| Breaking change during extraction | [H/M/L]    | [H/M/L] | Semantic versioning, deprecation period |
| Ownership vacuum                  | [H/M/L]    | [H/M/L] | Assign team before extraction           |
| Version sprawl                    | [H/M/L]    | [H/M/L] | Enforce upgrade policy                  |

## Decision

☐ **Proceed with extraction** - All criteria met
☐ **Defer extraction** - Criteria not met, re-evaluate on [date]
☐ **Alternative approach** - [Describe: shared module, copy, etc.]

**Rationale**: [Brief explanation of decision]

Migration Plan Checklist

Phase 1: Preparation (Week 1)

• Document current API surface
• Identify all consumers (direct and transitive)
• Establish version numbering scheme (SemVer)
• Create library repository with CI/CD
• Set up package publishing (NuGet, npm, PyPI, etc.)
• Document breaking change policy
• Assign ownership team with on-call rotation

Phase 2: Initial Release (Week 2)

• Extract code into library repository
• Ensure test coverage ≥ 80%
• Create API documentation
• Publish v1.0.0 (or appropriate version)
• Migrate first consumer (lowest risk)
• Verify functionality in staging environment
• Document migration steps for other consumers

Phase 3: Consumer Migration (Weeks 3-4)

• Notify all consumers of migration timeline
• Provide migration guide with examples
• Support each consumer during migration
• Track migration progress:

Phase 4: Stabilisation (Week 5+)

• Remove original code from source locations
• Monitor library usage metrics
• Address any post-migration issues
• Establish regular release cadence
• Document lessons learned

Rollback Plan

If migration fails for any consumer:

1. Consumer reverts to previous version (before library dependency)
2. Library team investigates and patches
3. Consumer re-attempts migration with patched version
4. If repeated failures: consider consumer-specific fork or delay

Success Criteria

• All consumers successfully migrated
• No production incidents attributed to library
• Library version published and consumable
• Original code removed from source repositories
• Documentation complete and accessible