Analyzing Projects

Systematic approaches to understanding codebases, identifying patterns, and mapping system architecture.

When to Use This Skill

• Onboarding to a new codebase
• Understanding unfamiliar code before making changes
• Investigating how features are implemented
• Mapping dependencies between modules
• Identifying architectural patterns in use

Core Analysis Framework

The 5-Layer Discovery Process

Layer 1: Surface Scan
  └─ Entry points, config files, directory structure

Layer 2: Dependency Mapping
  └─ Package managers, imports, module relationships

Layer 3: Architecture Recognition
  └─ Patterns (MVC, hexagonal, microservices)

Layer 4: Flow Tracing
  └─ Request paths, data flow, state management

Layer 5: Quality Assessment
  └─ Test coverage, code health, technical debt

Phase 1: Surface Scan

Entry Point Discovery

Start by identifying how the application launches:

1. Look for standard entry files:

   • main.*, index.*, app.*, server.*
   • cmd/ directory (Go)
   • src/main/ (Java)
   • bin/ scripts

2. Check configuration files:

   • package.json (scripts.start, main)
   • Makefile, Taskfile
   • Docker/Compose files
   • CI/CD configs (.github/workflows/)

3. Map directory structure:

   Quick heuristics:
   ├── src/           → Source code
   ├── lib/           → Internal libraries
   ├── pkg/           → Public packages (Go)
   ├── internal/      → Private packages (Go)
   ├── tests/         → Test files
   ├── docs/          → Documentation
   ├── scripts/       → Build/deploy scripts
   └── config/        → Configuration
   

Initial Questions to Answer

• What language(s) and framework(s)?
• What's the build system?
• How is the app deployed?
• Where are the main entry points?

Phase 2: Dependency Mapping

Package Manager Analysis

Internal Module Relationships

1. Trace imports from entry points

2. Build a mental model of layers:

   Presentation Layer (routes, controllers, views)
         ↓
   Application Layer (services, use cases)
         ↓
   Domain Layer (entities, business logic)
         ↓
   Infrastructure Layer (database, external APIs)
   

3. Identify shared utilities imported across modules

Phase 3: Architecture Recognition

Common Patterns to Identify

Architecture Questions

• How are concerns separated?
• Where does business logic live?
• How are external dependencies abstracted?
• What's the data access pattern?

Phase 4: Flow Tracing

Request Path Analysis

For web applications, trace a request end-to-end:

HTTP Request
    ↓
Router/Routes (maps URL → handler)
    ↓
Middleware (auth, logging, validation)
    ↓
Controller/Handler (orchestrates)
    ↓
Service/Use Case (business logic)
    ↓
Repository/DAO (data access)
    ↓
Database/External API

State Management Analysis

For frontend applications:

• Where is state stored? (Redux, Zustand, Context)
• How does data flow? (unidirectional, bidirectional)
• What triggers re-renders?

Phase 5: Quality Assessment

Code Health Indicators

Technical Debt Markers

• TODO/FIXME comments
• Disabled tests
• Large functions (>50 lines)
• Deep nesting (>4 levels)
• Duplicated code blocks
• Hardcoded values

Analysis Strategies by Goal

Goal: Make a Bug Fix

1. Find where the bug manifests
2. Trace back to the root cause
3. Understand the affected area only
4. Check for related tests

Goal: Add a New Feature

1. Find similar existing features
2. Understand the patterns they use
3. Map the modules that need changes
4. Identify integration points

Goal: Full Codebase Understanding

1. Complete all 5 phases
2. Document architecture decisions
3. Create a mental map of key flows
4. Identify ownership areas

Parallel Analysis Pattern

When exploring a large codebase, parallelize by module:

Spawn subagents for each major area:
├─ Subagent 1: Analyze src/auth (authentication module)
├─ Subagent 2: Analyze src/api (API layer)
├─ Subagent 3: Analyze src/db (data layer)
├─ Subagent 4: Analyze src/ui (frontend)
└─ Subagent 5: Analyze tests/ (test patterns)

Synthesize findings into unified architecture view.

Output Templates

Quick Architecture Summary

## Project Overview
- **Language**: [Primary language]
- **Framework**: [Main framework]
- **Architecture**: [Pattern identified]
- **Entry Point**: [Main file]

## Key Modules
| Module | Responsibility | Key Files |
|--------|----------------|-----------|
| [Name] | [What it does] | [Files]   |

## Data Flow
[Request lifecycle diagram]

## Notable Patterns
- [Pattern 1]: [Where/how used]
- [Pattern 2]: [Where/how used]

Onboarding Checklist

## Getting Started
- [ ] Clone and install dependencies
- [ ] Run the app locally
- [ ] Run the test suite
- [ ] Trace one request end-to-end
- [ ] Find where [core feature] is implemented

Anti-Patterns to Avoid

1. Analysis Paralysis - Don't try to understand everything before starting
2. Ignoring Tests - Tests often document expected behavior
3. Skipping Config - Configuration reveals deployment context
4. Surface-Only - Don't stop at directory structure
5. Assuming Patterns - Verify patterns, don't assume from naming

Quick Reference

SURFACE SCAN:
  entry points → config files → directory structure

DEPENDENCY MAP:
  package manager → import tracing → layer identification

ARCHITECTURE:
  pattern recognition → separation of concerns → abstractions

FLOW TRACING:
  request path → data flow → state management

QUALITY CHECK:
  test coverage → code health → technical debt

Designing APIs

Principles and patterns for designing clean, consistent, and maintainable APIs.

When to Use This Skill

• Designing new API endpoints
• Reviewing API contracts
• Planning API versioning strategies
• Defining request/response schemas
• Building GraphQL schemas
• Documenting APIs

REST API Design Principles

Resource-Oriented Design

APIs should be organized around resources, not actions:

GOOD (Resource-oriented):
GET    /users           → List users
GET    /users/123       → Get user 123
POST   /users           → Create user
PUT    /users/123       → Update user 123
DELETE /users/123       → Delete user 123

BAD (Action-oriented):
POST   /getUsers
POST   /createUser
POST   /updateUser
POST   /deleteUser

HTTP Method Semantics

URL Structure Patterns

Collection:     /users
Item:           /users/{id}
Nested:         /users/{id}/posts
Action:         /users/{id}/activate (POST only, for non-CRUD)
Filter:         /users?status=active&role=admin
Pagination:     /users?page=2&limit=20
Sort:           /users?sort=created_at&order=desc

Request Design

Path Parameters vs Query Parameters

Request Body Patterns

// POST /users - Create
{
  "email": "user@example.com",
  "name": "John Doe",
  "role": "admin"
}

// PATCH /users/123 - Partial update
{
  "name": "Jane Doe"
}

// Bulk operations - POST /users/bulk
{
  "operations": [
    { "action": "create", "data": { "email": "..." } },
    { "action": "update", "id": "123", "data": { "name": "..." } }
  ]
}

Response Design

Consistent Response Envelope

// Success response
{
  "data": { ... },
  "meta": {
    "timestamp": "2024-01-15T10:30:00Z",
    "requestId": "abc123"
  }
}

// Collection response with pagination
{
  "data": [ ... ],
  "meta": {
    "total": 100,
    "page": 2,
    "limit": 20,
    "hasMore": true
  }
}

// Error response
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request data",
    "details": [
      { "field": "email", "message": "Invalid email format" }
    ]
  },
  "meta": {
    "timestamp": "2024-01-15T10:30:00Z",
    "requestId": "abc123"
  }
}

HTTP Status Code Guidelines

Status Code Decision Tree

Success?
├─ Yes
│  ├─ Returning data? → 200 OK
│  ├─ Created resource? → 201 Created
│  └─ No content? → 204 No Content
└─ No
   ├─ Client's fault?
   │  ├─ Bad syntax? → 400 Bad Request
   │  ├─ Not authenticated? → 401 Unauthorized
   │  ├─ Not authorized? → 403 Forbidden
   │  ├─ Not found? → 404 Not Found
   │  └─ Validation failed? → 422 Unprocessable Entity
   └─ Server's fault? → 500 Internal Server Error

API Versioning Strategies

URL Path Versioning (Recommended)

/api/v1/users
/api/v2/users

Pros: Explicit, easy to understand, easy to route Cons: URL changes between versions

Header Versioning

GET /api/users
Accept: application/vnd.myapi.v2+json

Pros: Clean URLs Cons: Hidden version, harder to test

Query Parameter Versioning

/api/users?version=2

Pros: Flexible, easy to test Cons: Can be forgotten, pollutes query string

GraphQL Design Patterns

Schema-First Design

type User {
  id: ID!
  email: String!
  name: String!
  posts: [Post!]!
  createdAt: DateTime!
}

type Post {
  id: ID!
  title: String!
  content: String!
  author: User!
  createdAt: DateTime!
}

type Query {
  user(id: ID!): User
  users(filter: UserFilter, page: PageInput): UserConnection!
}

type Mutation {
  createUser(input: CreateUserInput!): User!
  updateUser(id: ID!, input: UpdateUserInput!): User!
  deleteUser(id: ID!): Boolean!
}

Input Types Pattern

input CreateUserInput {
  email: String!
  name: String!
  role: Role = USER
}

input UpdateUserInput {
  email: String
  name: String
  role: Role
}

input UserFilter {
  status: UserStatus
  role: Role
  search: String
}

Pagination Patterns

# Cursor-based (recommended for large datasets)
type UserConnection {
  edges: [UserEdge!]!
  pageInfo: PageInfo!
}

type UserEdge {
  node: User!
  cursor: String!
}

type PageInfo {
  hasNextPage: Boolean!
  hasPreviousPage: Boolean!
  startCursor: String
  endCursor: String
}

# Offset-based (simpler, for smaller datasets)
type UserList {
  items: [User!]!
  total: Int!
  page: Int!
  limit: Int!
}

Authentication & Authorization

Authentication Patterns

Authorization Responses

Not authenticated → 401 Unauthorized
  (User identity unknown)

Not authorized → 403 Forbidden
  (User known, but lacks permission)

Error Handling Patterns

Standardized Error Format

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "User with ID 123 not found",
    "target": "user",
    "details": [
      {
        "code": "INVALID_ID",
        "message": "The provided ID does not exist",
        "target": "id"
      }
    ],
    "innererror": {
      "trace": "abc123",
      "timestamp": "2024-01-15T10:30:00Z"
    }
  }
}

Common Error Codes

API Documentation

OpenAPI/Swagger Structure

openapi: 3.0.3
info:
  title: My API
  version: 1.0.0

paths:
  /users:
    get:
      summary: List users
      parameters:
        - name: status
          in: query
          schema:
            type: string
            enum: [active, inactive]
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserList'

components:
  schemas:
    User:
      type: object
      required: [id, email]
      properties:
        id:
          type: string
        email:
          type: string
          format: email

Anti-Patterns to Avoid

1. Verbs in URLs - Use /users not /getUsers
2. Ignoring HTTP Methods - Use proper methods, not POST for everything
3. Inconsistent Naming - Pick snake_case or camelCase, stick with it
4. Leaking Implementation - Don't expose internal IDs or DB structure
5. Missing Pagination - Always paginate collections
6. Ignoring Idempotency - PUT/DELETE must be idempotent
7. No Versioning - Plan for API evolution from day one

Quick Reference

RESOURCE DESIGN:
  /resources           → Collection
  /resources/{id}      → Item
  /resources/{id}/sub  → Nested

HTTP METHODS:
  GET     → Read (safe, idempotent)
  POST    → Create (not idempotent)
  PUT     → Replace (idempotent)
  PATCH   → Update (idempotent)
  DELETE  → Remove (idempotent)

STATUS CODES:
  200 OK, 201 Created, 204 No Content
  400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found
  500 Internal Server Error

VERSIONING:
  /api/v1/resources (recommended)

PAGINATION:
  ?page=2&limit=20 (offset)
  ?cursor=abc123&limit=20 (cursor)

Designing Architecture

Principles and patterns for designing maintainable, scalable, and robust software systems.

When to Use This Skill

• Designing new systems or features
• Choosing between architectural patterns
• Making technology decisions
• Reviewing system design
• Planning for scalability
• Refactoring legacy systems

Core Architecture Principles

SOLID Principles

The Dependency Rule

Outer layers depend on inner layers, NEVER the reverse.

┌─────────────────────────────────────┐
│     Frameworks & Drivers           │  ← Database, Web, UI
├─────────────────────────────────────┤
│     Interface Adapters             │  ← Controllers, Presenters, Gateways
├─────────────────────────────────────┤
│     Application Business Rules     │  ← Use Cases
├─────────────────────────────────────┤
│     Enterprise Business Rules      │  ← Entities
└─────────────────────────────────────┘

Dependencies point INWARD only.

Architectural Patterns

Layered Architecture

┌─────────────────────────────────────┐
│     Presentation Layer             │  ← UI, API Controllers
├─────────────────────────────────────┤
│     Application Layer              │  ← Use Cases, Services
├─────────────────────────────────────┤
│     Domain Layer                   │  ← Business Logic, Entities
├─────────────────────────────────────┤
│     Infrastructure Layer           │  ← Database, External APIs
└─────────────────────────────────────┘

Use when: Traditional applications, clear separation needed Avoid when: High-performance needs, event-driven systems

Hexagonal Architecture (Ports & Adapters)

           ┌───────────────┐
           │   Primary     │
           │   Adapters    │  ← REST API, CLI, GraphQL
           └───────┬───────┘
                   │
        ┌──────────▼──────────┐
        │                     │
        │   ┌───────────┐     │
        │   │   Core    │     │
Primary │   │  Domain   │     │ Secondary
Ports   │   │  Logic    │     │ Ports
        │   └───────────┘     │
        │                     │
        └──────────┬──────────┘
                   │
           ┌───────▼───────┐
           │   Secondary   │
           │   Adapters    │  ← Database, Message Queue, External API
           └───────────────┘

Use when: Testability is critical, multiple interfaces needed Avoid when: Simple CRUD applications

Microservices Architecture

┌─────────┐  ┌─────────┐  ┌─────────┐
│ Service │  │ Service │  │ Service │
│    A    │  │    B    │  │    C    │
└────┬────┘  └────┬────┘  └────┬────┘
     │            │            │
     └────────────┴────────────┘
                  │
           ┌──────▼──────┐
           │   Message   │
           │    Bus      │
           └─────────────┘

Use when: Independent scaling, team autonomy, polyglot needs Avoid when: Small teams, simple domains, tight coupling required

Event-Driven Architecture

Event Source → Event Bus → Event Handlers
     │              │              │
     ▼              ▼              ▼
  Produces    Routes Events    Consumes
  Events      (Kafka, RabbitMQ)  Events

Use when: Async processing, decoupling, audit trails Avoid when: Immediate consistency required, simple workflows

Design Patterns

Creational Patterns

Structural Patterns

Behavioral Patterns

Domain-Driven Design Concepts

Strategic Design

Tactical Patterns

System Design Considerations

Scalability Patterns

Resilience Patterns

Data Consistency Patterns

Technology Decision Framework

When to Use a Database

When to Use Message Queues

Architecture Decision Records (ADR)

Template

# ADR-001: [Title]

## Status
[Proposed | Accepted | Deprecated | Superseded by ADR-XXX]

## Context
[Why is this decision needed?]

## Decision
[What is the decision?]

## Consequences
### Positive
- [Benefit 1]
- [Benefit 2]

### Negative
- [Trade-off 1]
- [Trade-off 2]

## Alternatives Considered
1. [Alternative 1] - [Why rejected]
2. [Alternative 2] - [Why rejected]

Anti-Patterns to Avoid

1. Big Ball of Mud - No clear structure, everything depends on everything
2. Golden Hammer - Using one pattern for all problems
3. Premature Optimization - Designing for scale before proving need
4. Analysis Paralysis - Over-designing, never shipping
5. Distributed Monolith - Microservices with tight coupling
6. Anemic Domain Model - Entities with only getters/setters
7. God Object - One class that does everything
8. Leaky Abstraction - Implementation details leak through interfaces

Decision Checklist

Before finalizing an architecture decision, verify:

• Does it solve the actual problem?
• Is it the simplest solution that works?
• Can the team maintain it?
• Does it align with existing patterns?
• Is it testable?
• Can it evolve as requirements change?
• Are the trade-offs acceptable?
• Is the decision documented?

Quick Reference

SOLID:
  S - Single Responsibility
  O - Open/Closed
  L - Liskov Substitution
  I - Interface Segregation
  D - Dependency Inversion

PATTERNS:
  Layered     → Simple, clear separation
  Hexagonal   → Testable, adaptable
  Microservices → Scalable, independent
  Event-Driven  → Decoupled, async

DDD BUILDING BLOCKS:
  Entity, Value Object, Aggregate
  Repository, Domain Event, Domain Service

SCALABILITY:
  Horizontal scaling, Caching, Sharding, CDN

RESILIENCE:
  Circuit Breaker, Retry, Bulkhead, Timeout

Designing Tests

Strategies and patterns for designing effective, maintainable test suites.

When to Use This Skill

• Planning test coverage for new features
• Choosing between testing approaches (TDD, BDD)
• Designing integration or E2E tests
• Improving existing test suites
• Setting up testing infrastructure
• Debugging flaky tests

The Testing Pyramid

                 ┌─────────┐
                 │   E2E   │  ← Few, slow, expensive
                 │  Tests  │     (Selenium, Playwright)
                 ├─────────┤
                 │         │
              ┌──┤ Integr- │  ← Some, medium speed
              │  │  ation  │     (API tests, DB tests)
              │  │  Tests  │
              │  ├─────────┤
              │  │         │
              │  │  Unit   │  ← Many, fast, cheap
              │  │  Tests  │     (Pure functions, isolated)
              └──┴─────────┘

Test-Driven Development (TDD)

The Red-Green-Refactor Cycle

     ┌─────────────────────────────────┐
     │                                 │
     ▼                                 │
┌─────────┐    ┌─────────┐    ┌────────┴──┐
│   RED   │───▶│  GREEN  │───▶│ REFACTOR  │
│  Write  │    │  Make   │    │  Clean    │
│ failing │    │   it    │    │   up      │
│  test   │    │  pass   │    │  code     │
└─────────┘    └─────────┘    └───────────┘

TDD Best Practices

1. Write the test first - Don't write production code without a failing test
2. Write the minimal test - One behavior per test
3. Write the minimal code - Just enough to pass
4. Refactor ruthlessly - Clean up after green
5. Run tests frequently - After every small change

TDD Example Flow

# Step 1: RED - Write failing test
def test_calculate_total_with_discount():
    order = Order(items=[Item(price=100)])
    order.apply_discount(10)  # 10%
    assert order.total() == 90

# Step 2: GREEN - Minimal implementation
class Order:
    def __init__(self, items):
        self.items = items
        self.discount = 0

    def apply_discount(self, percent):
        self.discount = percent

    def total(self):
        subtotal = sum(i.price for i in self.items)
        return subtotal * (100 - self.discount) / 100

# Step 3: REFACTOR - Clean up (if needed)

Behavior-Driven Development (BDD)

Gherkin Syntax

Feature: Shopping Cart
  As a customer
  I want to add items to my cart
  So that I can purchase them later

  Scenario: Add item to empty cart
    Given I have an empty cart
    When I add a product "Widget" priced at $10
    Then my cart should contain 1 item
    And my cart total should be $10

  Scenario: Apply discount code
    Given I have a cart with total $100
    When I apply discount code "SAVE10"
    Then my cart total should be $90

BDD Benefits

• Tests as documentation
• Shared language with stakeholders
• Focus on behavior, not implementation
• Easy to understand test intent

Test Design Patterns

Arrange-Act-Assert (AAA)

def test_user_registration():
    # Arrange - Set up preconditions
    user_data = {"email": "test@example.com", "password": "secure123"}
    user_service = UserService(mock_repository)

    # Act - Perform the action
    result = user_service.register(user_data)

    # Assert - Verify the outcome
    assert result.success is True
    assert result.user.email == "test@example.com"

Given-When-Then (BDD style)

def test_order_cancellation():
    # Given - a confirmed order
    order = create_confirmed_order()

    # When - the customer cancels it
    order.cancel()

    # Then - the order is cancelled and refund initiated
    assert order.status == "cancelled"
    assert order.refund_initiated is True

Test Data Builders

class UserBuilder:
    def __init__(self):
        self.email = "default@test.com"
        self.name = "Test User"
        self.role = "user"

    def with_email(self, email):
        self.email = email
        return self

    def with_role(self, role):
        self.role = role
        return self

    def build(self):
        return User(email=self.email, name=self.name, role=self.role)

# Usage
admin = UserBuilder().with_role("admin").build()

Object Mother Pattern

class TestUsers:
    @staticmethod
    def admin():
        return User(email="admin@test.com", role="admin")

    @staticmethod
    def customer():
        return User(email="customer@test.com", role="customer")

    @staticmethod
    def guest():
        return User(email=None, role="guest")

Mocking Strategies

When to Mock

Mock Types

Mocking Example

# Using unittest.mock
from unittest.mock import Mock, patch

def test_send_email_on_registration():
    # Arrange
    mock_email_service = Mock()
    user_service = UserService(email_service=mock_email_service)

    # Act
    user_service.register({"email": "test@example.com"})

    # Assert
    mock_email_service.send_welcome_email.assert_called_once_with("test@example.com")

# Using patch decorator
@patch("app.services.EmailService")
def test_with_patch(mock_email_class):
    mock_email_class.return_value.send.return_value = True
    # Test code...

Integration Test Patterns

Database Tests

import pytest
from testcontainers.postgres import PostgresContainer

@pytest.fixture(scope="session")
def database():
    with PostgresContainer("postgres:15") as postgres:
        yield postgres.get_connection_url()

def test_user_persistence(database):
    repo = UserRepository(database)
    user = User(email="test@example.com")

    repo.save(user)
    retrieved = repo.find_by_email("test@example.com")

    assert retrieved.email == user.email

API Tests

def test_create_user_endpoint(client):
    response = client.post("/api/users", json={
        "email": "new@example.com",
        "password": "secure123"
    })

    assert response.status_code == 201
    assert response.json["email"] == "new@example.com"
    assert "id" in response.json

E2E Test Patterns

Page Object Model

class LoginPage:
    def __init__(self, page):
        self.page = page
        self.email_input = page.locator("#email")
        self.password_input = page.locator("#password")
        self.submit_button = page.locator("button[type=submit]")

    def login(self, email, password):
        self.email_input.fill(email)
        self.password_input.fill(password)
        self.submit_button.click()
        return DashboardPage(self.page)

# Usage
def test_successful_login(page):
    login_page = LoginPage(page)
    dashboard = login_page.login("user@example.com", "password")
    assert dashboard.welcome_message.is_visible()

E2E Best Practices

1. Use stable selectors - data-testid, not CSS classes
2. Wait for conditions - Not arbitrary sleeps
3. Isolate test data - Each test gets fresh data
4. Test critical paths - Happy paths, key user journeys
5. Keep them fast - Parallelize, minimize scope

Test Coverage Strategy

What to Cover

Coverage Metrics

Meaningful Coverage

HIGH VALUE:
  ✓ Core business logic
  ✓ Data transformations
  ✓ Error handling
  ✓ Security-sensitive code

LOW VALUE:
  ✗ Getters/setters
  ✗ Constructor-only classes
  ✗ Framework boilerplate
  ✗ Configuration files

Handling Flaky Tests

Common Causes

Flaky Test Checklist

• Is the test relying on timing?
• Is there shared state between tests?
• Is there an external dependency?
• Is the order of execution assumed?
• Is there non-deterministic data?

Test Organization

File Structure

tests/
├── unit/                    # Unit tests
│   ├── services/
│   │   └── test_user_service.py
│   └── models/
│       └── test_order.py
├── integration/             # Integration tests
│   ├── api/
│   │   └── test_user_endpoints.py
│   └── repositories/
│       └── test_user_repository.py
├── e2e/                     # End-to-end tests
│   └── test_checkout_flow.py
├── fixtures/                # Shared fixtures
│   └── factories.py
└── conftest.py              # Pytest configuration

Naming Conventions

# Pattern: test_[what]_[condition]_[expected]

def test_calculate_total_with_discount_returns_reduced_price():
    pass

def test_login_with_invalid_password_raises_auth_error():
    pass

def test_order_when_cancelled_sends_refund_notification():
    pass

Anti-Patterns to Avoid

1. Testing implementation, not behavior - Tests break on refactor
2. Large test methods - Hard to debug, unclear intent
3. Excessive mocking - Tests don't reflect reality
4. Shared mutable state - Tests affect each other
5. Ignoring test failures - Broken windows effect
6. Testing private methods - Coupling to implementation
7. No assertion - Tests that can't fail
8. Copy-paste tests - Maintenance nightmare

Quick Reference

PYRAMID:
  Unit (70%) → Integration (20%) → E2E (10%)

TDD CYCLE:
  Red → Green → Refactor

PATTERNS:
  AAA: Arrange-Act-Assert
  Builder: Fluent test data creation
  Page Object: E2E abstraction

MOCK WHEN:
  External APIs, Database (unit), Time, Random

COVERAGE:
  70-80% line, focus on business logic

NAMING:
  test_[what]_[condition]_[expected]

Managing Git

Best practices for version control, branching strategies, and collaborative development.

When to Use This Skill

• Setting up branching strategies
• Writing commit messages
• Handling merges and conflicts
• Managing releases
• Code review workflows
• Maintaining clean history

Branching Strategies

Git Flow

main ─────●─────────────────────●─────────────────●────▶
           \                   /                 /
release     \───────●─────────●                 /
              \                                /
develop ───────●───────●───────●──────●───────●────────▶
                \       \       \      \
feature          \───────●───────●      \───●───●
                          \              \
hotfix                     \              \───●────▶ main

Use when: Scheduled releases, multiple versions supported

GitHub Flow

main ─────●─────●─────●─────●─────●────▶
           \   /       \   /       \   /
feature     ●─●         ●─●         ●─●
            PR          PR          PR

Use when: Continuous deployment, simple workflow

Trunk-Based Development

main ─────●──●──●──●──●──●──●──●──●──●────▶
           │  │  │  │  │  │  │  │  │  │
          ●   ●  ●  ●  ●  ●  ●  ●  ●  ●
          Small, frequent commits (often direct to main)

Use when: High trust teams, strong CI/CD, frequent deploys

Commit Message Conventions

Conventional Commits

<type>(<scope>): <subject>

<body>

<footer>

Types

Good vs Bad Commits

BAD:
  - "fix"
  - "update code"
  - "WIP"
  - "changes"
  - "asdfasdf"

GOOD:
  - "fix(auth): prevent session timeout on idle"
  - "feat(cart): add quantity validation"
  - "refactor(api): extract common error handling"

Commit Body Guidelines

fix(payment): prevent double charge on retry

The payment gateway timeout was causing the retry logic to submit
duplicate charges. Added idempotency key to prevent double-processing.

Closes #1234

• First line: 50 chars max, imperative mood
• Body: Wrap at 72 chars, explain why, not what
• Footer: Reference issues, breaking changes

Branch Naming Conventions

Pattern

<type>/<ticket>-<short-description>

Examples

Branch Rules

1. Lowercase with hyphens
2. Include ticket number when available
3. Keep short but descriptive
4. Delete after merge

Git Workflow Commands

Daily Workflow

# Start new feature
git checkout main
git pull origin main
git checkout -b feature/AUTH-123-add-login

# Work on feature
git add -p                    # Stage hunks interactively
git commit -m "feat(auth): add login form"

# Keep up to date
git fetch origin
git rebase origin/main        # Preferred: clean history
# OR
git merge origin/main         # Alternative: preserves context

# Push and create PR
git push -u origin feature/AUTH-123-add-login

Useful Commands

Cleanup Commands

# Delete merged branches locally
git branch --merged | grep -v main | xargs git branch -d

# Prune remote tracking branches
git fetch --prune

# Clean untracked files (careful!)
git clean -fd

Handling Conflicts

Conflict Resolution Flow

1. Identify conflicts
   git status

2. Open conflicted files
   <<<<<<< HEAD
   your changes
   =======
   their changes
   >>>>>>> feature-branch

3. Resolve (keep one, combine, or rewrite)

4. Mark resolved
   git add <resolved-file>

5. Continue
   git rebase --continue   # if rebasing
   git commit              # if merging

Prevention Strategies

1. Small, frequent merges - Reduce conflict scope
2. Communication - Coordinate on shared files
3. Feature flags - Reduce long-lived branches
4. Clear ownership - Minimize overlapping work

Pull Request Best Practices

PR Checklist

• Branch is up to date with main
• Tests pass locally
• Linting passes
• Self-review completed
• Documentation updated
• Ticket/issue linked
• Screenshots for UI changes

PR Size Guidelines

PR Description Template

## Summary
Brief description of changes

## Changes
- Added X
- Modified Y
- Removed Z

## Testing
- [ ] Unit tests added
- [ ] Manual testing done

## Screenshots (if applicable)
[Before/After images]

## Related Issues
Closes #123

Release Management

Semantic Versioning

MAJOR.MINOR.PATCH
  │     │     │
  │     │     └── Bug fixes (backward compatible)
  │     └── New features (backward compatible)
  └── Breaking changes

Release Process

# Create release branch
git checkout -b release/v1.2.0 develop

# Bump version, update changelog
# ... make changes ...

# Merge to main and tag
git checkout main
git merge release/v1.2.0
git tag -a v1.2.0 -m "Release v1.2.0"
git push origin main --tags

# Merge back to develop
git checkout develop
git merge release/v1.2.0

Changelog Format

# Changelog

## [1.2.0] - 2024-01-15
### Added
- OAuth2 authentication support

### Changed
- Improved error messages

### Fixed
- Memory leak in cache handler

### Deprecated
- Old authentication method (use OAuth2)

### Removed
- Legacy API v1 endpoints

Git Hooks

Common Hooks

Example pre-commit

#!/bin/sh
# .git/hooks/pre-commit

# Run linter
npm run lint
if [ $? -ne 0 ]; then
  echo "Linting failed. Please fix errors."
  exit 1
fi

# Run tests
npm test
if [ $? -ne 0 ]; then
  echo "Tests failed. Please fix before committing."
  exit 1
fi

Using Husky (Node.js)

// package.json
{
  "husky": {
    "hooks": {
      "pre-commit": "lint-staged",
      "commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
    }
  }
}

Troubleshooting

Common Issues

Recovery Commands

# Undo last commit (keep changes)
git reset --soft HEAD~1

# Undo last commit (discard changes)
git reset --hard HEAD~1

# Recover deleted branch
git reflog
git checkout -b recovered-branch <sha>

# Undo a pushed commit (safe)
git revert <sha>

Anti-Patterns to Avoid

1. Force pushing to shared branches - Breaks others' history
2. Giant commits - Hard to review, hard to bisect
3. Vague commit messages - "fix" tells nothing
4. Long-lived branches - Merge conflict hell
5. Committing generated files - Bloats repo, causes conflicts
6. Committing secrets - Security risk (even after removal)
7. Rebasing public history - Breaks collaborators
8. Ignoring CI failures - Broken windows effect

Quick Reference

BRANCHES:
  main       → Production (protected)
  develop    → Integration (Git Flow)
  feature/*  → New work
  fix/*      → Bug fixes
  hotfix/*   → Production emergencies

COMMITS:
  feat(scope): add feature
  fix(scope): fix bug
  docs(scope): update docs
  refactor(scope): restructure code

DAILY FLOW:
  git checkout -b feature/ticket-desc
  git add -p && git commit
  git rebase origin/main
  git push -u origin feature/ticket-desc

VERSIONING:
  MAJOR.MINOR.PATCH
  Breaking.Feature.Bugfix

Optimizing Performance

Strategies for identifying, analyzing, and resolving performance bottlenecks.

When to Use This Skill

• Application is running slowly
• High resource consumption (CPU, memory)
• Database queries are slow
• API response times are high
• Need to scale for more users
• Preparing for load testing

Performance Optimization Philosophy

The Golden Rules

1. Measure first - Never optimize without data
2. Optimize the right thing - Find the actual bottleneck
3. Keep it simple - Complexity often hurts performance
4. Test after - Verify the optimization worked
5. Document trade-offs - Performance often costs readability

The 80/20 Rule

80% of performance problems come from 20% of the code.

Focus on:
├── Hot paths (frequently executed code)
├── I/O operations (database, network, disk)
├── Memory allocation patterns
└── Algorithm complexity

Profiling Techniques

Types of Profiling

Profiling Workflow

1. Establish baseline
   └─ Measure current performance with realistic load

2. Identify hotspots
   └─ Profile to find where time/resources are spent

3. Form hypothesis
   └─ Why is this slow? What would make it faster?

4. Implement fix
   └─ Make ONE change at a time

5. Measure again
   └─ Did it help? By how much?

6. Repeat
   └─ Until performance goals are met

Common Profiling Commands

# Node.js
node --prof app.js
node --prof-process isolate-*.log > profile.txt

# Python
python -m cProfile -s cumtime app.py
py-spy record -o profile.svg -- python app.py

# Go
go test -cpuprofile cpu.prof -memprofile mem.prof -bench .
go tool pprof cpu.prof

# Database (PostgreSQL)
EXPLAIN ANALYZE SELECT * FROM users WHERE email = 'test@example.com';

Common Bottleneck Patterns

N+1 Query Problem

BAD (N+1 queries):
  SELECT * FROM posts;             -- 1 query
  SELECT * FROM users WHERE id=1;  -- N queries
  SELECT * FROM users WHERE id=2;
  ...

GOOD (2 queries):
  SELECT * FROM posts;
  SELECT * FROM users WHERE id IN (1, 2, 3, ...);

Detection: High query count relative to data returned Fix: Eager loading, batch fetching, JOINs

Unbounded Operations

BAD:
  SELECT * FROM logs;  -- Returns millions of rows

GOOD:
  SELECT * FROM logs
  WHERE created_at > NOW() - INTERVAL '1 day'
  LIMIT 100;

Detection: Memory spikes, timeouts Fix: Pagination, limits, streaming

Synchronous Blocking

BAD (blocking):
  result1 = fetch_api_1()  -- Wait 200ms
  result2 = fetch_api_2()  -- Wait 200ms
  return combine(result1, result2)  -- Total: 400ms

GOOD (parallel):
  [result1, result2] = await Promise.all([
    fetch_api_1(),
    fetch_api_2()
  ])  -- Total: ~200ms

Detection: Sequential I/O in traces Fix: Parallel execution, async/await

Excessive Allocation

BAD (allocates in loop):
  for item in large_list:
      result = []  # Allocates each iteration
      result.append(transform(item))

GOOD (pre-allocate):
  result = []
  for item in large_list:
      result.append(transform(item))

BEST (generator):
  def transform_all(items):
      for item in items:
          yield transform(item)

Detection: GC pressure, memory profiling Fix: Object pooling, pre-allocation, generators

Optimization Techniques

Database Optimization

Index Guidelines

-- Create index for frequently queried columns
CREATE INDEX idx_users_email ON users(email);

-- Composite index for multiple column queries
CREATE INDEX idx_orders_user_date ON orders(user_id, created_at);

-- Check if index is used
EXPLAIN ANALYZE SELECT * FROM users WHERE email = 'test@example.com';

Caching Strategies

Cache-aside pattern:
1. Check cache
2. If miss, query database
3. Store in cache
4. Return result

Memory Optimization

Frontend Performance

Core Web Vitals

Frontend Optimization Checklist

Loading Performance:
  ☐ Code splitting (lazy load routes/components)
  ☐ Tree shaking (remove unused code)
  ☐ Minification (JS, CSS)
  ☐ Compression (gzip, brotli)
  ☐ Image optimization (WebP, srcset, lazy loading)
  ☐ CDN for static assets

Runtime Performance:
  ☐ Virtualized lists for large data
  ☐ Debounce/throttle event handlers
  ☐ Memoization of expensive computations
  ☐ Avoid layout thrashing (batch DOM reads/writes)
  ☐ Use CSS transforms for animations
  ☐ Web Workers for heavy computation

Bundle Optimization

# Analyze bundle size
npx webpack-bundle-analyzer stats.json
npx source-map-explorer bundle.js

# Identify large dependencies
npx depcheck

API Performance

Response Time Targets

API Optimization Techniques

Batch Endpoints

BAD (multiple requests):
  GET /users/1
  GET /users/2
  GET /users/3

GOOD (batch):
  POST /users/batch
  { "ids": [1, 2, 3] }

Monitoring and Alerting

Key Metrics to Track

Alerting Thresholds

Critical (page immediately):
  - Error rate > 5%
  - p99 latency > 5s
  - Service down

Warning (notify during hours):
  - Error rate > 1%
  - p95 latency > 2s
  - Resource utilization > 80%

Logging for Performance

# Log slow operations
import time
import logging

def timed_operation(func):
    def wrapper(*args, **kwargs):
        start = time.time()
        result = func(*args, **kwargs)
        duration = time.time() - start
        if duration > 1.0:  # Log if > 1 second
            logging.warning(f"{func.__name__} took {duration:.2f}s")
        return result
    return wrapper

Performance Testing

Load Testing Tools

Load Test Example (k6)

import http from 'k6/http';
import { check, sleep } from 'k6';

export const options = {
  stages: [
    { duration: '1m', target: 50 },   // Ramp up
    { duration: '5m', target: 50 },   // Stay at 50 users
    { duration: '1m', target: 0 },    // Ramp down
  ],
  thresholds: {
    http_req_duration: ['p(95)<500'],  // 95% under 500ms
    http_req_failed: ['rate<0.01'],    // Error rate < 1%
  },
};

export default function () {
  const res = http.get('https://api.example.com/users');
  check(res, { 'status is 200': (r) => r.status === 200 });
  sleep(1);
}

Anti-Patterns to Avoid

1. Premature optimization - Optimize only proven bottlenecks
2. Optimizing without measuring - Guessing wastes time
3. Over-caching - Cache invalidation is hard
4. Ignoring database - Often the real bottleneck
5. Complex micro-optimizations - Usually not worth it
6. Not testing under load - Production behavior differs
7. Ignoring cold starts - First request matters too
8. Over-engineering - Simpler is often faster

Quick Reference

PROFILING FLOW:
  Measure → Identify → Hypothesize → Fix → Measure → Repeat

COMMON BOTTLENECKS:
  N+1 queries → Eager loading
  Unbounded data → Pagination
  Blocking I/O → Parallelization
  Excessive allocation → Object pooling

DATABASE:
  Index frequently queried columns
  Use EXPLAIN ANALYZE
  Add caching layer

CACHING:
  Cache-aside for general use
  TTL for time-based invalidation
  Invalidate on write for consistency

TARGETS:
  p50 < 100ms
  p95 < 500ms
  p99 < 1s

TOOLS:
  CPU: pprof, py-spy
  Memory: valgrind, memory_profiler
  Load: k6, locust
  DB: EXPLAIN, slow query log

Parallel Execution

CRITICAL: This skill teaches how to execute multiple tasks simultaneously for maximum efficiency.

The Fundamental Rule

ALL Task calls MUST be in a SINGLE assistant message for true parallelism.

If Task calls are in separate messages, they run SEQUENTIALLY, not in parallel.

Why Parallel Execution Matters

Sequential (SLOW - AVOID)

Message 1: Start Task A
           ↓ wait for completion
Message 2: Start Task B
           ↓ wait for completion
Message 3: Start Task C
           ↓ wait for completion

Total time = A + B + C = 90 seconds (if each takes 30s)

Parallel (FAST - USE THIS)

Message 1: Start Task A ─┐
           Start Task B ─┼─ All run simultaneously
           Start Task C ─┘

Total time ≈ max(A, B, C) = 30 seconds

Speedup: 3x faster with 3 parallel tasks

How to Execute in Parallel

Step 1: Identify Independent Tasks

Tasks are independent when:

• They don't depend on each other's output
• They don't modify the same files
• They can run in any order

Step 2: Launch ALL Tasks in ONE Message

<!-- CORRECT: All tasks in single message = PARALLEL -->
<task>
  <description>Analyze authentication module</description>
  <prompt>Review src/auth for security patterns...</prompt>
</task>

<task>
  <description>Analyze API layer</description>
  <prompt>Review src/api for REST best practices...</prompt>
</task>

<task>
  <description>Analyze database layer</description>
  <prompt>Review src/db for query optimization...</prompt>
</task>

Step 3: Collect and Synthesize Results

After all tasks complete, combine their findings into a unified response.

Parallelization Patterns

Pattern 1: Task-Based Parallelization

When you have N independent tasks, spawn N subagents:

Implementation Plan:
1. Implement auth module
2. Create API endpoints
3. Add database schema
4. Write unit tests
5. Update documentation

Launch 5 parallel subagents:
├─ Subagent 1: Implement auth module
├─ Subagent 2: Create API endpoints
├─ Subagent 3: Add database schema
├─ Subagent 4: Write unit tests
└─ Subagent 5: Update documentation

All 5 in ONE message!

Pattern 2: Directory-Based Parallelization

Analyze different directories simultaneously:

Codebase Structure:
├── src/auth/
├── src/api/
├── src/db/
└── src/ui/

Launch 4 parallel subagents:
├─ Subagent 1: Analyze src/auth
├─ Subagent 2: Analyze src/api
├─ Subagent 3: Analyze src/db
└─ Subagent 4: Analyze src/ui

Pattern 3: Perspective-Based Parallelization

Review from multiple angles at once:

Code Review Perspectives:
- Security vulnerabilities
- Performance bottlenecks
- Test coverage gaps
- Architecture patterns

Launch 4 parallel subagents:
├─ Subagent 1: Security review
├─ Subagent 2: Performance analysis
├─ Subagent 3: Test coverage review
└─ Subagent 4: Architecture assessment

Pattern 4: Adversarial Verification

Use conflicting mandates for thorough review:

Verification Subagents (all parallel):
├─ Syntax & Type Checker
├─ Test Runner
├─ Lint & Style Checker
├─ Security Scanner
└─ Build Validator

Then (sequential, after above complete):
├─ False Positive Filter
├─ Missing Issues Finder
└─ Context Validator

TodoWrite Integration

When using parallel execution, mark ALL parallel tasks as in_progress simultaneously:

Before Launching Parallel Tasks

{
  "todos": [
    { "content": "Analyze auth module", "status": "in_progress", "activeForm": "Analyzing auth module" },
    { "content": "Analyze API layer", "status": "in_progress", "activeForm": "Analyzing API layer" },
    { "content": "Analyze database layer", "status": "in_progress", "activeForm": "Analyzing database layer" },
    { "content": "Synthesize findings", "status": "pending", "activeForm": "Synthesizing findings" }
  ]
}

After Each Task Completes

Mark as completed as results come in:

{
  "todos": [
    { "content": "Analyze auth module", "status": "completed", "activeForm": "Analyzing auth module" },
    { "content": "Analyze API layer", "status": "completed", "activeForm": "Analyzing API layer" },
    { "content": "Analyze database layer", "status": "in_progress", "activeForm": "Analyzing database layer" },
    { "content": "Synthesize findings", "status": "pending", "activeForm": "Synthesizing findings" }
  ]
}

When to Parallelize

Good Candidates

When NOT to Parallelize

Performance Impact

Assuming each task takes ~30 seconds

Common Mistakes

Mistake 1: Separate Messages

WRONG (Sequential):
Message 1: "I'll start analyzing the auth module..."
           <task>Analyze auth</task>
Message 2: "Now let me analyze the API..."
           <task>Analyze API</task>

RIGHT (Parallel):
Message 1: "I'll analyze all modules in parallel..."
           <task>Analyze auth</task>
           <task>Analyze API</task>
           <task>Analyze DB</task>

Mistake 2: Announcing Before Acting

WRONG:
"I'm going to launch three parallel tasks to analyze the codebase."
[waits for response]
"Now launching the tasks..."

RIGHT:
"Launching three parallel analysis tasks now:"
<task>...</task>
<task>...</task>
<task>...</task>

Mistake 3: Forgetting Synthesis

WRONG:
Just dump all task outputs without integration

RIGHT:
After receiving all results, synthesize:
- Identify common themes
- Resolve contradictions
- Prioritize findings
- Create unified recommendations

Parallel Execution Checklist

Before launching parallel tasks, verify:

• Tasks are truly independent
• No shared file modifications
• No sequential dependencies
• All tasks in SINGLE message
• TodoWrite updated with all in_progress
• Synthesis step planned

Template: Parallel Analysis

## Launching Parallel Analysis

I'm analyzing this codebase from multiple perspectives simultaneously.

### Parallel Tasks

<task description="Security Review">
Analyze for security vulnerabilities, focusing on:
- Authentication/authorization
- Input validation
- Secrets handling
</task>

<task description="Performance Review">
Analyze for performance issues, focusing on:
- N+1 queries
- Memory leaks
- Blocking operations
</task>

<task description="Test Coverage Review">
Analyze test coverage, focusing on:
- Missing test cases
- Edge cases
- Integration tests
</task>

### Synthesis (after all complete)

[Combine findings into prioritized report]

Quick Reference

RULE #1:
  ALL Task calls in SINGLE message = PARALLEL
  Task calls in SEPARATE messages = SEQUENTIAL

PATTERNS:
  Task-based:       One subagent per task
  Directory-based:  One subagent per directory
  Perspective-based: One subagent per viewpoint
  Adversarial:      Multiple competing reviewers

TODOWRITE:
  Mark ALL parallel tasks as in_progress BEFORE launching
  Mark each as completed AFTER receiving results

SPEEDUP:
  N parallel tasks ≈ Nx faster
  (5 tasks @ 30s each: 150s → 30s)

CHECKLIST:
  ☐ Tasks independent?
  ☐ No shared files?
  ☐ No dependencies?
  ☐ All in ONE message?
  ☐ Synthesis planned?