📦 deps(skills): sync thirdparty skills

2026-05-29 08:33:55 +00:00
parent b7eb57f5da
commit b4c88b32be
25 changed files with 3033 additions and 0 deletions
@@ -0,0 +1,220 @@
+# Architecture Analysis
+
+Techniques for analyzing system structure, dependencies, and component relationships.
+
+## Dependency Mapping
+
+### Forward Dependencies
+
+What a component relies on:
+1. **Direct imports** — explicit dependencies in code
+2. **Indirect references** — called through interfaces
+3. **Runtime dependencies** — configuration, environment
+4. **Data dependencies** — shared state, databases
+
+### Reverse Dependencies
+
+What relies on this component:
+1. **Direct dependents** — explicit imports from other modules
+2. **Interface consumers** — components using this API
+3. **Side effect consumers** — code relying on mutations
+4. **Event subscribers** — listeners for this component's events
+
+### Circular Dependencies
+
+Red flags:
+- A imports B, B imports A
+- Longer cycles: A → B → C → A
+- Implicit cycles through shared state
+
+Resolution strategies:
+- Extract shared code to separate module
+- Introduce interface/abstraction layer
+- Invert dependency direction
+- Break into smaller components
+
+## Layer Identification
+
+### Detecting Layers
+
+Look for:
+- **Directional flow** — data/control flows one way
+- **Abstraction levels** — concrete → abstract as you ascend
+- **Responsibility clustering** — similar concerns grouped
+- **Interface boundaries** — clear contracts between groups
+
+### Common Layer Patterns
+
+**Three-tier**:
+- Presentation (UI, API endpoints)
+- Business logic (domain, workflows)
+- Data access (repositories, queries)
+
+**Hexagonal/Clean**:
+- Core domain (entities, business rules)
+- Application layer (use cases, orchestration)
+- Infrastructure (frameworks, external services)
+- Interfaces (controllers, adapters)
+
+**Microservices**:
+- Service boundary (API gateway)
+- Service logic (domain per service)
+- Data layer (per-service database)
+- Cross-cutting (auth, logging, monitoring)
+
+### Layer Violations
+
+Violations indicate architectural drift:
+- Lower layer imports higher layer
+- Business logic in presentation layer
+- Data access code in domain entities
+- Infrastructure concerns leaking into core
+
+## Interface Analysis
+
+### Contract Definition
+
+Examine:
+- **Input types** — what does it accept?
+- **Output types** — what does it return?
+- **Error modes** — what can fail, how?
+- **Side effects** — mutations, I/O, state changes
+- **Invariants** — what must always be true?
+
+### API Quality
+
+Strong interfaces show:
+- **Cohesion** — methods belong together
+- **Minimal surface** — small, focused API
+- **Clear contracts** — types tell the story
+- **Stability** — changes don't cascade
+- **Composability** — works well with others
+
+Weak interfaces show:
+- **Kitchen sink** — unrelated methods bundled
+- **Leaky abstractions** — implementation details exposed
+- **Unstable** — frequent breaking changes
+- **Rigid** — hard to extend or compose
+
+## Component Relationships
+
+### Relationship Types
+
+**Composition**:
+- Component owns sub-components
+- Lifecycles coupled
+- Strong cohesion
+- Example: `Page` owns `Header`, `Footer`
+
+**Aggregation**:
+- Component references others
+- Independent lifecycles
+- Loose coupling
+- Example: `ShoppingCart` references `Product`
+
+**Dependency**:
+- Uses another component's interface
+- No ownership
+- Can be swapped
+- Example: `AuthService` uses `Database`
+
+**Association**:
+- Knows about but doesn't own
+- Weak relationship
+- Often bidirectional
+- Example: `User` ↔ `Post` (many-to-many)
+
+### Coupling Analysis
+
+**Low coupling** (good):
+- Communicate through interfaces
+- Few shared assumptions
+- Changes localized
+- Easy to test in isolation
+
+**High coupling** (risky):
+- Direct field access
+- Shared mutable state
+- Knowledge of implementation
+- Changes ripple widely
+
+## Architectural Pattern Recognition
+
+### Layered Architecture
+
+Indicators:
+- Unidirectional dependencies (top → bottom)
+- Each layer uses only layer below
+- Clear separation of concerns
+
+Trade-offs:
+- ✓ Simple, well-understood
+- ✓ Easy to enforce rules
+- ✗ Can become rigid
+- ✗ Performance overhead
+
+### Event-Driven Architecture
+
+Indicators:
+- Pub/sub or message queues
+- Decoupled components
+- Asynchronous communication
+- Event sourcing patterns
+
+Trade-offs:
+- ✓ Scalable, resilient
+- ✓ Loose coupling
+- ✗ Harder to reason about flow
+- ✗ Eventual consistency challenges
+
+### Microservices
+
+Indicators:
+- Service per bounded context
+- Independent deployment
+- API-based communication
+- Decentralized data
+
+Trade-offs:
+- ✓ Independent scaling
+- ✓ Technology diversity
+- ✗ Distributed system complexity
+- ✗ Operational overhead
+
+## Analysis Workflow
+
+### Top-Down
+
+Start broad, narrow focus:
+1. **System boundaries** — what's in scope?
+2. **Major components** — high-level modules
+3. **Component interactions** — how they communicate
+4. **Internal structure** — zoom into each component
+5. **Implementation** — code-level details
+
+### Bottom-Up
+
+Start specific, build understanding:
+1. **Entry point** — main(), server start, UI root
+2. **Call graph** — trace execution paths
+3. **Cluster calls** — group related functionality
+4. **Extract components** — identify logical boundaries
+5. **Map relationships** — connect the pieces
+
+### Targeted
+
+Focus on specific concern:
+1. **Define question** — what are you trying to understand?
+2. **Identify relevant code** — where does this happen?
+3. **Trace dependencies** — what does it touch?
+4. **Analyze impact** — what would changing this affect?
+5. **Document findings** — capture insights
+
+## Documentation Extraction
+
+From architecture analysis, capture:
+- **Component diagram** — boxes and arrows
+- **Dependency graph** — what imports what
+- **Layer diagram** — abstraction levels
+- **Sequence diagrams** — interaction flows
+- **Decision records** — why this structure?