system-architecture

Skill from elevanaltd/oa
Category: discovered
Tags: github, community
Version: 1.0.0
Author: walid
Downloads: 0
Updated: 2025-11-22
Source: elevanaltd/oa
Download the latest version (v1.0.0) from this page.
SKILL.md

# System Architecture Skill (FLUKE)
## Systemic Thinking and Ripple Analysis

> **TYPE**: Domain Skill (FLUKE)
> **CATEGORY**: Analysis
> **PRIORITY**: High
> **AUTO_INJECT**: true

---

## Skill Purpose

This skill provides **systematic thinking capabilities** for understanding how code changes ripple through complex systems.

**Core Principle**: "Whole house before brick - local changes demand systemic thinking."

---

## When This Skill Activates

**Trigger Keywords**:
- "architecture"
- "system design"
- "ripple effect"
- "dependencies"
- "integration"
- "how does this affect"

**Affinity Skills** (co-loaded):
- `pattern-synthesis`
- `integration-design`
- `build-execution` (during ACTUAL ARM)

---

## Core Capabilities

### 1. Ripple Analysis

**Purpose**: Map how code changes propagate through system

**Process**:
```
1. Identify change point
2. Map direct dependencies (imports, calls)
3. Trace data flow paths
4. Identify shared state interactions
5. Find distant coupling
6. Document integration points
```

**Output Template**:
```markdown
## Ripple Analysis: [Change Description]

### Direct Impact
- File: `path/to/file.ts`
  - Function: `functionName()`
  - Reason: Direct import/call

### Data Flow Impact
- [Source] → [Transform] → [Destination]
- Breaking change: YES/NO
- Migration required: YES/NO

### Shared State Impact
- State: `globalState.auth`
- Readers: [list of components]
- Writers: [list of components]
- Risk: [low/medium/high]

### Integration Points
- API endpoint: `/api/users`
- Database: `users` table
- External services: Auth0, Stripe
- Event handlers: `onUserLogin`

### Recommendations
1. [Action to minimize ripple]
2. [Test coverage needed]
3. [Migration strategy if needed]
```

### 2. Dependency Mapping

**Purpose**: Understand component relationships

**Actions**:
- Create visual dependency diagrams
- Identify circular dependencies
- Find tight coupling hotspots
- Recommend decoupling strategies

### 3. System Coherence Validation

**Purpose**: Ensure changes maintain architectural integrity

**Validations**:
- Layer boundary respect (no UI→DB direct)
- Dependency direction (high→low level)
- Pattern consistency
- Abstraction appropriateness

---

## Decision Gates

### Before Adding Code

**Question**: "Will this change introduce new system complexity?"

**Analysis**:
```
1. Count new dependencies: [number]
2. Count new integration points: [number]
3. Assess coupling increase: [low/medium/high]
4. Evaluate: Is complexity essential or accumulative?
```

**Decision**:
- Essential complexity → Proceed with documentation
- Accumulative complexity → Find simpler approach

### Before Refactoring

**Question**: "Does this refactoring improve or obscure system understanding?"

**Criteria**:
- MORE obvious → Good refactoring
- MORE mysterious → Bad refactoring

**Rule of Three**: Abstract only after pattern appears 3+ times

---

## ARM Context Modulation

### CONCEPTUAL ARM (Design D0-D3)
**Emphasis**: HIGH (+0.30 boost)

**Use**:
- Design alternative architectures
- Evaluate trade-offs
- Map component relationships
- Plan integration strategies

### ACTUAL ARM (Build B0-B5)
**Emphasis**: MEDIUM (+0.20 boost)

**Use**:
- Validate implementation against design
- Ensure ripple awareness before coding
- Maintain systemic thinking during build

---

## LOGOS Cognition Alignment

This skill has **high affinity** with LOGOS agents because:

1. **Pattern Recognition**: Sees structural connections
2. **Systematic Thinking**: Reveals order in complexity
3. **Synthesis**: Combines competing architectural approaches
4. **Transcendence**: Finds third-way architectures beyond trade-offs

**Boost**: LOGOS agents receive +0.25 confidence when this skill loads

---

## Example: Ripple Analysis in Action

**Scenario**: Adding user authentication

```markdown
## Ripple Analysis: Add JWT Authentication

### Direct Impact
- `src/middleware/auth.ts` (NEW)
- `src/server.ts` (MODIFIED - add middleware)
- `src/types/user.ts` (MODIFIED - add JWT claims)

### Data Flow Impact
Request → Auth Middleware → JWT Validation → User Context → Route Handler
- Breaking: YES (unauthenticated requests now fail)
- Migration: Add public route whitelist

### Shared State Impact
- New state: `req.user` (populated by middleware)
- Readers: All route handlers
- Writers: Auth middleware only
- Risk: LOW (single writer pattern)

### Integration Points
- API endpoints: ALL `/api/*` routes (except whitelist)
- Database: `users` table (for validation)
- External: JWT signing service
- Events: `onAuthFailure` (new)

### Dependencies Added
- `jsonwebtoken` library (MIT license ✓)
- `bcrypt` for password hashing (Apache 2.0 ✓)

### Test Coverage Required
1. Valid JWT → Access granted
2. Expired JWT → 401 Unauthorized
3. Malformed JWT → 401 Unauthorized
4. Missing JWT on protected route → 401
5. Valid JWT on public route → Allowed (no check)

### Recommendations
1. Implement public route whitelist to minimize breaking changes
2. Add JWT refresh token mechanism for UX
3. Monitor auth failure rates in production
4. Document authentication flow for future maintainers
```

**Result**: Systematic analysis reveals:
- Scope of impact (all API routes)
- Migration strategy (whitelist)
- Test requirements (5 key scenarios)
- UX improvement opportunity (refresh tokens)

---

## Anti-Patterns to Avoid

### ❌ Local Optimization, Global Degradation
```typescript
// WRONG: Optimized locally, breaks globally
function getUserFast(id) {
  return cache[id]; // Fast! But stale data breaks other features
}
```

### ❌ Mystery Abstraction
```typescript
// WRONG: Abstract pattern that appears once
class SingletonFactoryBuilderAdapter {
  // Used in exactly one place - unnecessary complexity
}
```

### ❌ Ignoring Ripples
```typescript
// WRONG: Change without analysis
// Change shared constant without checking readers
export const MAX_RETRIES = 10; // Was 3, now breaks rate limiting
```

---

## Success Metrics

**This skill succeeds when**:
- ✅ Code changes documented with ripple analysis
- ✅ Integration tests cover identified impact points
- ✅ System coherence maintained or improved
- ✅ Complexity is essential, not accumulative
- ✅ Future maintainers understand change impact

---

**VERSION**: 1.0.0
**LAST_UPDATED**: 2025-11-15
**MAINTAINER**: holistic-orchestrator
**STATUS**: Active