---
name: team-principles
description: |
  Apply and review adherence to our Team engineering principles during code review, refactoring,
  design, and AI-assisted development. Use this skill when reviewing code for unnecessary
  complexity, premature abstraction, or cleverness over clarity; when reviewing AI-generated
  code for accountability and correctness; when checking defensive coding practices and
  early error detection; or when assessing simplicity in design and implementation decisions.
  Covers: avoiding hasty abstractions, clarity over cleverness, simplicity, prevention and
  early detection, and responsible AI usage.
metadata:
  category: Team
  version: "1.0.0"
  source: principles
---

# Team Principles

Our engineering principles for how teams write code, make decisions, use AI, and deliver value —
with clarity, simplicity, accountability, and prevention built in.

## When to Apply

Apply this skill when:
- Reviewing code for unnecessary complexity, clever tricks, or hard-to-understand patterns
- Reviewing abstractions introduced before there is clear need for them
- Reviewing AI-assisted or AI-generated code for human accountability and correctness
- Checking defensive patterns, early error detection, and prevention of issues
- Assessing whether code is as simple as possible while still meeting requirements
- Reviewing whether changes are deployed safely and progressively
- Reviewing delivery decisions for iterative value and pragmatic focus

## Principles Overview

| Principle | Coverage | Reference |
|-----------|----------|-----------|
| Avoid Hasty Abstractions | Full guidance | `principles/avoid-hasty-abstractions.md` |
| Clarity Over Cleverness | Full guidance | `principles/clarity-over-cleverness.md` |
| Keep It as Simple as Possible | Full guidance | `principles/keep-it-as-simple-as-possible.md` |
| Prioritise Prevention and Early Detection | Full guidance | `principles/prioritise-prevention-and-early-detection.md` |
| Use AI Responsibly | Full guidance | `principles/use-ai-responsibly.md` |
| Changes are "live" When Enabled | Process reminder | See below |
| Deliver Value Iteratively | Process reminder | See below |
| Developer Experience Matters | Process reminder | See below |
| Get Stuff Done | Process reminder | See below |

## Quick Review Checklist

Use this for a fast adherence scan. Load individual principle files for detailed guidance.

### Avoid Hasty Abstractions
- [ ] Abstractions are introduced based on observed, repeated patterns — not anticipated reuse
- [ ] Shared code serves consumers without requiring flags or special-case logic

### Clarity Over Cleverness
- [ ] A developer unfamiliar with a module can read a function and understand its purpose within seconds
- [ ] Naming conventions are consistent and follow shared team standards

### Keep It as Simple as Possible
- [ ] The solution avoids unnecessary layers, services, or framework complexity
- [ ] Changes can be made without widespread knock-on effects

### Prioritise Prevention and Early Detection
- [ ] Contracts are explicit and checked (types, schemas, or tests)
- [ ] Compliance and quality checks run automatically before release

### Use AI Responsibly
- [ ] A named owner remains accountable for each decision and change
- [ ] AI-generated outputs are reviewed and validated before merging or release

## Process Reminders

The following principles are primarily about delivery culture, team process, or operational habits. Surface these as awareness prompts.

> **Changes are "live" When Enabled and Outcomes are Checked**: Teams separate deploying code from releasing functionality — a change can be deployed safely without making it visible to users until the team explicitly enables it using feature flags or progressive delivery. This reduces blast radius, supports fast rollback, and creates space for controlled rollouts and measurement. A change is only truly "live" when it is enabled, observed, and outcomes are confirmed.

> **Deliver Value Iteratively Whilst Innovating**: Teams make deliberate trade-offs between trying new ideas and delivering proven value, using established approaches by default and only introducing new technology when there is a clear, written justification tied to a measurable outcome. Innovation is expected but time-boxed with explicit success criteria and a decision at the end. Learnings are shared so the whole organisation benefits, not just the immediate team.

> **Developer Experience Matters**: Shared code, libraries, APIs, and services are treated as products with developers as their users — friction in finding, understanding, or extending them is treated as a defect. Maintain up-to-date documentation with usage examples, fast and reliable CI pipelines, clear contribution guidelines, and reproducible local development setup. Good developer experience attracts contributions, reduces onboarding time, and accelerates delivery across the organisation.

> **Get Stuff Done**: Teams organise around finishing valuable work rather than maximising individual utilisation — limiting work in progress and swarming to unblock delivery keeps flow moving and reduces queues and handoffs. Stand-ups walk the board rather than the person, and stories should regularly reach "done" within a sprint rather than accumulating as partially-started work. If new work is being pulled in before existing work is finished, that is a signal to rebalance.

## How to Use

Load the relevant principle file when you need detailed guidance:

```
principles/avoid-hasty-abstractions.md               — when reviewing premature or unnecessary abstractions
principles/clarity-over-cleverness.md                — when reviewing overly complex or clever code
principles/keep-it-as-simple-as-possible.md          — when reviewing design or implementation for unnecessary complexity
principles/prioritise-prevention-and-early-detection.md — when reviewing defensive patterns and error handling
principles/use-ai-responsibly.md                     — when reviewing AI-assisted or AI-generated code
```