integration-rules

Files (1)

• SKILL.md

SKILL.md (first lines)

# Integration Rules

These rules are mandatory for all code review and development work involving multi-component systems.

## Vertical Slice Principle

Every task MUST deliver a thin, working end-to-end path:

| Good (Vertical Slice) | Bad (Horizontal Layer) |
|------------------------|------------------------|
| "User can send message" (UI + API + LLM + response display) | "Create all database tables" |
| "Display product list" (API call + domain filter + UI render) | "Build all API endpoints" |
| "Process payment" (UI form + gateway + order update) | "Create all UI components" |

## Walking Skeleton

The FIRST deliverable of any multi-component feature must be a walking skeleton:
- One request flows through ALL layers
- Returns real data (not hardcoded/mocked)
- Proves the architecture connects end-to-end
- Does NOT need to be feature-complete — just connected

## Contract-First Development

When two components will communicate:

| Step | Action | Artifact |
|------|--------|----------|
| 1 | Define interface before implementation | TypeScript interface, OpenAPI schema, or protobuf |
| 2 | Both sides code against the contract | Import shared types or generated clients |
| 3 | Contract test validates both sides | Test that producer output matches consumer expectation |

## Integration Test Requirements

| Boundary | Required Test |
|----------|---------------|
| HTTP API endpoint | Request with real HTTP client, validate response shape + status |
| Database operation | Testcontainers with real queries, validate data persisted |
| Message queue | Real producer + consumer, validate message delivered |
| External service | Test Double with `// Test Double rationale:` (only exception) |
| In-process module boundary | Real function call, validate input/output contract |

## Orphan Detection

Code without a live entry point is dead-on-arrival.

**Valid entry points** (at least one required per new module):
- HTTP/WebSocket handler
- CLI command handler
- Event/message listener
- Scheduled job/cron handler
- Exported function called by a module that has an entry point

**Detection**: Trace from new code upward — if no path reaches an entry point, the code is an orphan.

## Detection Checklist

When reviewing code, flag:
1. New module/service without any caller (orphan code)
2. Task structured as horizontal layer instead of vertical slice
3. Two components communicating without shared interface/contract
4. New boundary crossing without integration test
5. Use case with DB/API dependency but only unit tests
6. Component "works in isolation" but not wired to any entry point
7. Interface defined but no contract test validating compatibility

From rocky2431/ultra-builder-pro, MIT.

More from rocky2431/ultra-builder-pro