---

name: Branerail description: CTO-level architectural advisor for AI-native development. Use this skill whenever you encounter code design decisions, architecture discussions, system resilience questions, or any work touching: "architecture", "design", "scale", "dependencies", "state", "failure", "blast radius", "refactor", "migrate", "optimize", "resilience", "consistency", "observability", "bottleneck", "coupling", "monolith", "microservices", "distributed", "concurrency", "data flow", "system design", or any prompt suggesting code-first thinking when design-first thinking is needed. This skill integrates with Claude Code to review generated code for architectural soundness, define design systems via design.md, and guide teams toward CTO-level thinking. Trigger aggressively on architectural questions—this is where AI adds the most leverage.

Branerail Skill: CTO-Level Agent for AI-Native Development

Core principle: AI generates code at lightspeed. Your job is to conduct the orchestra, not play a single instrument. In an AI-native world, architectural thinking—not syntactic fluency—separates valuable builders from those building houses of cards.

---

When to Trigger This Skill

Use this skill for:

1. Architecture from scratch: Building new systems without a design blueprint
2. Code quality audits: Reviewing AI-generated code for architectural soundness
3. Resilience analysis: Understanding failure modes and cascade effects
4. State and data flow: Clarifying ownership, mutations, and consistency
5. Scaling decisions: Planning for growth, identifying bottlenecks
6. Refactoring and migration: Restructuring existing systems safely
7. Observability and feedback loops: Designing monitoring and alerting
8. Design system definition: Creating DESIGN.md for AI agent consistency
9. Dependency mapping: Understanding what breaks when something is removed
10. Concurrency and consistency: Handling race conditions, distributed state

Trigger keywords (use liberally):

• architecture, design, system design, blueprint
• scale, scaling, growth, bottleneck
• failure, resilience, fault tolerance, crash
• state, stateful, state management, ownership
• blast radius, cascade, coupling, tight coupling, loose coupling
• data flow, data consistency, sync, eventual consistency
• refactor, rewrite, migration, monolith, microservices
• observability, monitoring, logging, alerting, tracing
• optimize, performance, latency, throughput
• dependency, dependent, independent, circular dependency
• concurrency, race condition, deadlock, locking, mutex
• distributed, consensus, replication, consistency
• single point of failure, SPOF, redundancy
• contract, interface, API, contract drift
• DESIGN.md, design system, design tokens, brand consistency
• code review, audit, architectural review
• Claude Code, code generation, AI-generated code

---

Part 1: The Three Pillars of Systems Thinking

Before shipping any logic, answer these three questions with certainty. If you cannot, your system is fragile.

Pillar 1: Where Does State Live?

The Question: What is the single source of truth for each mutable piece of data?

Why It Matters: Multiple components claiming ownership creates race conditions, sync bugs, and silent data corruption. AI-generated code often scatters state without a coherent strategy.

Audit Process:

1. Inventory mutable state: Every piece of data that changes (user profiles, order status, inventory counts, cache entries, feature flags, session tokens).
2. Identify authoritative owner: For each, which component is first to modify it?
3. Check for replicas: Do other components maintain copies? If yes:
   • Is this for performance (caching) or redundancy (failover)?
   • What is the reconciliation strategy?
   • Who wins in a conflict?
4. Trace mutation paths: When data changes, does every replica update? How?

Architecture Patterns:

| Pattern | Use When | Trade-offs | |---------|----------|-----------| | Single Source of Truth (DB) | Correctness is critical (payments, inventory, auth) | Higher latency (must hit DB) | | Write-Through Cache | High read volume, acceptable write latency | Must update cache after DB | | Write-Back Cache | Low write latency needed | Risk of cache loss before sync | | Event Sourcing | Need audit trail and point-in-time recovery | Complexity, eventual consistency | | CQRS | Read/write patterns differ radically | Query model sync complexity | | Distributed Consensus | Sync state across replicas (e.g., etcd, Raft) | Complex, higher latency |

Red Flags:

• "State is in A, but B caches it for performance."
• Multiple components modify the same data.
• No explicit ownership declared.
• Circular dependencies (A owns X, B owns Y, A reads Y to compute X).
• Cache invalidation strategy is "just invalidate everything."

Code Review Checklist:

• [ ] Every mutable variable has a declared owner.
• [ ] Non-owners read from the owner, not from stale copies.
• [ ] Writes go to the owner first, then propagate (if at all).
• [ ] Conflict resolution rules exist (write wins, read latest, timestamp-based).
• [ ] State schema is versioned; migrations are explicit.

---

Pillar 2: Where Does Feedback Live?

The Question: How do you know if your system is working? What alerts you to failures?

Why It Matters: A system without visibility is failing silently. By the time a user reports it, the damage may be irreversible.

Audit Process:

1. Identify critical operations: Data writes, API calls, job scheduling, external integrations, state syncs.
2. Define success and failure: What does "working" look like for each operation?
3. Instrument for visibility:
   • Structured logging (JSON, key-value pairs, not printf blobs).
   • Metrics (counters, latencies, error rates).
   • Distributed tracing (request ID propagation, span correlation).
   • Alerts (threshold-based, anomaly-based, custom rules).
4. Test observability: Can you reconstruct a failure from logs alone?

Logging Strategy:

✅ GOOD: Structured, contextual
{
  "timestamp": "2026-04-27T10:30:45Z",
  "service": "order-processor",
  "operation": "process_payment",
  "orderId": "order_12345",
  "customerId": "cust_67890",
  "status": "failed",
  "error": "payment_gateway_timeout",
  "retries_attempted": 3,
  "latency_ms": 5000,
  "trace_id": "tr_abc123def456"
}

❌ BAD: Unstructured, no context
[ERROR] Payment failed. Retrying...

Metrics to Track:

• Request count (by endpoint, by status)
• Request latency (p50, p95, p99)
• Error rate (by type, by service)
• Queue depth (for async jobs)
• Cache hit ratio
• State sync lag (for replicated data)
• Deployment frequency, lead time, MTTR

Alerting Strategy:

• Threshold-based: Error rate > 5% for 5 minutes
• Anomaly-based: Latency 3σ above baseline
• Custom logic: "If payment failures increase 10x in 1 hour, alert"
• Escalation: Page on-call for P1 (data loss, security), alert for P2 (degraded, slow)

Red Flags:

• "We log errors, but only when explicitly caught."
• No monitoring for silent failures (cron job that didn't run, queue that got stuck).
• Logs with data but no context (what was being attempted?).
• Alerts that trigger after customer impact.
• "We'll debug when users report issues."

Code Review Checklist:

• [ ] Every I/O operation logs success/failure with context.
• [ ] All error paths are instrumented (not just happy path).
• [ ] Request IDs propagate across service boundaries.
• [ ] Metrics are emitted (count, latency, errors).
• [ ] Alerts are defined for SLO violations.
• [ ] Logs are queryable (not syslog blobs; structured, indexed).

---

Pillar 3: What Breaks If I Delete This?

The Question: Can you trace the blast radius of every component?

Why It Matters: If you cannot articulate what happens when a piece is removed, you do not truly understand the system.

Audit Process:

1. Pick a component (service, module, function, data store, queue).
2. Simulate deletion:
   • What calls into it?
   • What depends on its output?
   • What happens to dependents if it's gone?
3. Continue recursively: Trace cascading effects.
4. Identify single points of failure (SPOF): Components with no fallback.
5. Measure blast radius: How many users, transactions, or features are affected?

Blast Radius Analysis:

Scenario: Delete the cache layer

A: Web → Cache → DB

If cache is deleted:
  - Reads go directly to DB (slower, but correct)
  - Throughput drops 10x
  - DB CPU spikes
  - Users on slow connections timeout
  - Blast radius: ALL users
  - Mitigation: Circuit breaker (fail fast instead of timing out)

Scenario: Delete the notification service

Orders → Notification Service → Email / SMS

If notification service is deleted:
  - Orders still process (good)
  - Users don't get confirmation emails (bad UX)
  - Blast radius: Marketing, customer trust
  - Mitigation: Queue notifications, retry asynchronously

Dependency Mapping:

| Component | Depends On | Depended On By | Fallback? | SPOF? | |-----------|-----------|----------------|-----------|-------| | Auth Service | DB | All services | No | YES | | Payment Gateway | External API | Orders | Retry + queue | Partial | | Cache | In-memory store | API | Direct DB read | No | | Notification | Message queue | Orders, Users | Queue message | No |

Red Flags:

• "I'm not sure what would break."
• Circular dependencies (A needs B, B needs A).
• Hidden dependencies through side effects, globals, or environment variables.
• No clear contract for a component (what are its inputs, outputs, failure modes?).
• A component has no fallback (single point of failure).

Code Review Checklist:

• [ ] Each component has explicit dependencies declared (imports, config, injected).
• [ ] No hidden global state.
• [ ] No circular dependencies.
• [ ] Fallback strategies exist for external dependencies.
• [ ] Circuit breakers or bulkheads isolate failures.
• [ ] Blast radius is documented (what features fail if this goes down?).
• [ ] The deletion test passes (you can mentally trace the impact).

---

Part 2: The Design Process Before Code

These practices slow you down. They save you from building on sand.

1. Sketch the Architecture (Before Prompting AI)

Workflow:

1. Draw boxes for major components (services, databases, caches, queues, external APIs).
2. Draw arrows for data flow (what data moves where, in what direction, how often).
3. Label arrows with data structures and frequency (e.g., "User order JSON, ~1000/sec").
4. Identify state owners on the diagram (which box is authoritative for each type of data).
5. Mark external dependencies (what lives outside your control? What can fail?).
6. Add fallbacks (what happens if that dependency is down?).

Example Diagram:

                    Client
                      |
                [API Gateway]
                /     |      \
            Order   User    Payment
            Service Service Service
              |       |        |
            [Order DB] [User DB] [Payment Gateway]
              |       |
            [Cache]  [Cache]
              |
           [Message Queue]
              |
          [Notification Service]
              |
         [Email / SMS Provider]

Blast radius analysis:
- If Order Service ↓: Can't create orders (orders = core feature)
- If User Service ↓: Can't login (cascade fail)
- If Cache ↓: Slower reads, but queries still work
- If Email Provider ↓: Orders process, confirmations queue, retried

Checkpoint: Can you sketch this in 5 minutes and explain it to someone else? If not, you don't understand it yet. Do not prompt AI.

---

2. Write a Design Document (DESIGN.md for Systems, Spec for Features)

Use design.md for visual design systems. Use *architectural specs