@gobing-ai/spur 0.3.80 → 0.3.81

package/plugins/sp/skills/taste-refactoring-architect/references/architecture-refactoring-playbook.md

@@ -0,0 +1,173 @@
+# Architecture Refactoring Playbook
+
+## 1. Definition of “better”
+A refactored architecture is better when it preserves required business behavior and delivery qualities while decreasing unnecessary complexity, coordination, operational burden, or irreversible commitments.
+
+A useful before/after scorecard tracks:
+- runtime components and dependencies,
+- synchronous call depth,
+- deployable units,
+- persistence technologies,
+- duplicated domain rules,
+- cross-team handoffs per representative change,
+- deployment lead time and failure rate,
+- incident frequency/blast radius/recovery time,
+- cost per useful business unit,
+- time for a new engineer to understand/change a critical flow.
+
+## 2. Simplification lenses
+
+### Capability lens
+Map components to business capabilities. Unmapped components are deletion candidates; multiple components for one capability may be consolidation candidates.
+
+### Change-coupling lens
+Inspect which components change together. If independent services are almost always changed/deployed together, the boundary may be false.
+
+### Runtime-coupling lens
+Inspect critical request paths. Long synchronous chains multiply latency and failure probability.
+
+### Data lens
+Identify sources of truth, replicas, caches, shared writes, synchronization, and reconciliation. Complexity often hides in data movement rather than boxes.
+
+### Ownership lens
+Map every component to one accountable team. Misalignment creates coordination tax and unreliable operations.
+
+### Failure lens
+For each dependency, ask what happens when it is slow, unavailable, duplicated, reordered, or partially successful.
+
+### Quality lens
+Tie each structural decision to a measurable quality requirement. Redundancy, isolation, caching, asynchronous processing, and extra deployment units may all be justified — but only by a requirement.
+
+## 3. Complexity budget
+Think of architecture complexity as a budget. Spend it only where it buys a material capability or quality.
+
+Common costs:
+- network boundaries,
+- distributed consistency,
+- async semantics,
+- schema evolution,
+- independent deployment pipelines,
+- observability surface,
+- access control surface,
+- operational ownership,
+- version compatibility,
+- data synchronization,
+- incident diagnosis.
+
+## 4. Refactoring patterns
+
+### Delete
+Remove dead services, queues, adapters, databases, caches, gateways, compatibility layers, feature flags, or pipelines after proving they are unused.
+
+### Inline
+Inline a thin service/module that only delegates and has no independent ownership, policy, scaling, security, or lifecycle reason.
+
+### Merge
+Merge components with the same owner, lifecycle, data, and change cadence when separation creates more coordination than isolation value.
+
+### Modularize in place
+Before extracting services, create explicit module boundaries, ownership, dependency rules, and tests inside the existing deployment unit.
+
+### Split by proven axis
+Split only where independence is valuable: ownership, security, scale, failure isolation, data lifecycle, or release cadence.
+
+### Replace bespoke with standard capability
+Retire custom schedulers, service discovery, retry frameworks, configuration systems, or deployment machinery when a standard platform/managed capability can satisfy requirements with less burden.
+
+### Strangle incrementally
+Place a seam around legacy behavior, route selected flows to a replacement, compare results, migrate consumers/data gradually, then delete the legacy path.
+
+### Collapse integration hops
+Remove unnecessary gateways/translators/brokers in a path where they add no policy, protocol, security, buffering, or ownership value.
+
+### Make data ownership explicit
+Assign one authoritative writer and expose controlled reads/events/APIs rather than shared writes.
+
+### Introduce async deliberately
+Use a queue/event log for buffering, fan-out, long-running work, temporal decoupling, or resilience. Pair it with idempotency, retries, DLQ/recovery, ordering assumptions, and observability.
+
+### Introduce cache deliberately
+Add cache only for measured cost/latency/load. Define key ownership, TTL/invalidation, stampede protection, consistency expectations, and failure behavior.
+
+## 5. Redesign triggers
+Redesign is warranted when evidence shows the architecture cannot economically or safely satisfy required qualities with local improvements.
+
+Strong triggers:
+- repeated systemic incidents caused by structural coupling,
+- scaling ceiling that cannot be relieved locally,
+- security/compliance requires a new trust boundary,
+- core data model prevents correctness,
+- common changes require coordinated releases across many independently owned systems,
+- platform is unsupported and blocks safe delivery,
+- operational cost dominates product value despite optimization.
+
+Weak triggers (not enough alone):
+- “old technology”,
+- “not cloud native”,
+- “competitors use microservices”,
+- desire for a new framework,
+- preference for a pattern,
+- aesthetically messy diagrams.
+
+## 6. Quality-preservation matrix
+For each refactor, explicitly assess:
+
+| Quality | Questions |
+|---|---|
+| Functionality | Are all user/business flows preserved? Any edge-case behavior lost? |
+| Reliability | Does failure isolation improve or regress? What new dependencies appear? |
+| Recoverability | Are backup, replay, restore, rollback, RTO/RPO preserved? |
+| Performance | What happens to latency, throughput, capacity, and tail behavior? |
+| Security | Do trust boundaries, least privilege, auditability, and secrets improve? |
+| Data | Is ownership clearer? Are consistency and retention semantics unchanged? |
+| Operability | Is it easier to deploy, observe, diagnose, and recover? |
+| Maintainability | Does a common change touch fewer concepts/components/teams? |
+| Compatibility | Are existing consumers/contracts preserved during migration? |
+| Cost | Does total runtime + engineering + operational cost improve? |
+
+## 7. Architecture fitness functions
+Examples:
+- no domain package may depend on infrastructure packages except through defined ports,
+- no synchronous request path may exceed N remote calls,
+- critical APIs must meet p99 latency and error-rate thresholds,
+- all externally consumed schemas pass compatibility checks,
+- critical business flows meet availability SLO,
+- restore drill meets RTO/RPO,
+- no production component lacks an owning team and runbook,
+- no service may directly write another service’s owned tables,
+- representative feature change must require no more than N team handoffs,
+- architecture cost per transaction stays below threshold.
+
+## 8. Migration safety
+Each migration step should be independently deployable and observable.
+
+Use as appropriate:
+- consumer inventory,
+- contract tests,
+- compatibility adapters,
+- feature flags,
+- shadow reads/writes,
+- dual run with reconciliation,
+- canary rollout,
+- traffic splitting,
+- backfill checkpoints,
+- immutable migration logs,
+- rollback-safe schema changes,
+- explicit decommission criteria.
+
+## 9. Architecture decision quality
+Record ADRs for decisions that are expensive to reverse, constrain many teams, or encode important trade-offs.
+
+A concise ADR contains:
+- context/constraints,
+- decision,
+- alternatives considered,
+- trade-offs,
+- consequences,
+- validation/fitness functions,
+- review trigger/date.
+
+Delete or supersede stale ADRs when their constraints disappear.
+
+## 10. “Simple” does not mean simplistic
+A simpler architecture may still include redundancy, asynchronous processing, partitioning, isolation, or multiple data stores if those elements are essential to required quality. The goal is justified complexity, not minimal box count.

package/plugins/sp/skills/taste-refactoring-architect/references/research-basis.md

@@ -0,0 +1,28 @@
+# Research Basis and Industry Practices
+
+This skill treats “STOA” as **state-of-the-art architecture techniques** rather than as a single formal standard. If a team uses a specific internal framework named STOA, map its terminology into the intervention ladder and quality model in this skill.
+
+## Quality attributes
+ISO/IEC 25010:2023 provides a modern product quality model with nine characteristics and sub-characteristics. The skill uses it as a vocabulary for preservation contracts and quality trade-offs, while adding delivery/operability concerns that architecture teams usually need in practice.
+
+## Well-Architected thinking
+AWS Well-Architected uses six pillars: operational excellence, security, reliability, performance efficiency, cost optimization, and sustainability. The skill borrows the idea that architecture is evaluated through explicit trade-offs and operational evidence, not pattern compliance.
+
+Google Cloud’s Architecture Framework emphasizes robust system design, decoupling where useful, documentation, high availability/scalability, and cost-conscious design. This skill uses these ideas but explicitly warns against adding decoupling when it increases complexity without delivering a quality benefit.
+
+## Evolutionary architecture
+Evolutionary architecture practices emphasize guided incremental change, fitness functions, reversible decisions, and continuous feedback. The skill therefore requires measurable fitness functions and prefers small migration steps over big-bang rewrites.
+
+## Team/service ownership
+Single-team ownership patterns such as STOSA and modern team-topology thinking reinforce the principle that service boundaries should have clear operational ownership. The skill treats shared/no ownership as a refactoring smell and favors boundaries that align responsibility, data, change cadence, and operations.
+
+## Incremental modernization
+Strangler-style modernization and compatibility seams are used as migration techniques when replacement is necessary. The objective is not to preserve legacy structure, but to preserve behavior while shrinking risk and allowing progressive deletion.
+
+## Architecture documentation
+C4-style abstraction levels and ADRs are compatible with this skill: use diagrams to communicate current/target structures and ADRs to record consequential trade-offs. Documentation is useful only when it remains consistent with runtime evidence.
+
+## Guiding synthesis
+The distinctive bias of this skill is:
+
+> **Reduce first. Re-boundary second. Enhance only against a named quality gap. Redesign last. Prove every structural change against preserved features and delivery qualities.**

package/plugins/sp/skills/taste-refactoring-tests/README.md

@@ -0,0 +1,28 @@
+# taste-refactoring-tests
+
+A reusable agent skill for refactoring existing unit tests so the test suite improves **real delivery quality** instead of creating an “always-pass” illusion.
+
+Its core bias is simple:
+
+> A test earns its place by detecting meaningful regressions.
+
+The skill uses a graded intervention model:
+
+- T0 KEEP
+- T1 DIRECT REMOVE
+- T2 SUGGEST REMOVE
+- T3 STRENGTHEN
+- T4 SIMPLIFY / DE-BRITTLE
+- T5 ADD MISSING PROTECTION
+- T6 RE-DESIGN TEST STRATEGY
+- T7 QUARANTINE / INVESTIGATE
+
+The package includes:
+- `SKILL.md` — operational agent instructions
+- `references/test-refactoring-playbook.md` — detailed techniques and heuristics
+- `references/research-basis.md` — industry-practice basis and concepts
+- `checklists/daily-test-review.md` — quick daily checklist
+- `examples/review-template.md` — reusable assessment format
+- `examples/refactor-example.md` — worked example of converting green-but-weak tests into failure-sensitive tests
+
+The skill is intentionally skeptical of vanity coverage, tautological assertions, mock-heavy choreography, flaky retries, and tests that merely prove that the test setup works.