World Class Engineering

---
name: world-class-engineering
description: Use when designing, building, reviewing, or upgrading production software that must be secure, performant, maintainable, scalable, and user-centred, and when verifying a change before claiming done or opening a PR via the six-phase build, types, lint, tests, security, and diff-review gate (READY/NOT READY).
metadata:
  portable: true
  compatible_with:
  - claude-code
  - codex
---

# World-Class Engineering
Acknowledgement: Shared by Peter Bamuhigire, techguypeter.com, +256 784 464178.

<!-- dual-compat-start -->
## Use When

- Use when designing, building, reviewing, or upgrading production software systems that must be secure, performant, maintainable, scalable, and user-centered. Apply before writing specs, code, architecture, APIs, databases, mobile apps, SaaS platforms, or ERP systems.

## Workflow

- For premium, commercial, executive-facing, website, SaaS, ERP, POS, dashboard, or agency-delivery work, pair with `premium-software-product-execution` before locking scope, pricing, UX, reporting, or proof assets.

## References

- [Tech-lead learning loop](references/tech-lead-learning-loop.md): role clarity,
  implement-reflect-adjust, trust, communication, and ownership transfer.

- Use the `references/` directory for deep detail after reading the core workflow below.
- Load `references/language-standards.md` when implementation or documentation needs explicit language, localisation, naming, or terminology standards.
- Load [references/verification-loop.md](references/verification-loop.md) immediately before claiming a feature, fix, or refactor is done or opening a PR: the six-phase build, types, lint, tests, security, and diff-review gate with a fixed READY/NOT READY report (absorbed from the retired `verification-loop` skill).
## Book-informed practice route

For scenario contracts, review focus, AI collaboration, failure-aware architecture, and Git recovery, load [the slice, review, and recovery practice](references/slice-review-and-recovery-practice.md).
<!-- dual-compat-end -->
Use this skill as the baseline operating system for all serious implementation skills in this repository. It defines what world-class software development, engineering, and management look like when the goal is not just to ship code, but to build software that is valuable, trusted, maintainable, fast to evolve, and worth paying for.

## Output Contract

Every output must satisfy all of these:

- Solve a real user and business problem with explicit constraints, not just a technical prompt.
- Improve one or more of: user value, revenue leverage, trust, speed, reliability, or maintainability.
- Choose an architecture that supports change, not just initial delivery.
- Make security, observability, performance, and failure handling first-class concerns.
- Prefer boring, reliable defaults over clever but fragile abstractions.
- Leave the codebase, workflow, and operating posture better than before.

For meaningful work, produce these artifacts explicitly:

- problem frame and success criteria
- value-stream slice and batch-size choice
- architecture or module shape
- data, API, and failure assumptions
- validation and release evidence
- operational and ownership notes

Close meaningful work with the **Delivery Definition of Done** pack
(`skill-composition-standards/references/delivery-definition-of-done.md`): tests
plus evidence, release plan, rollback plan, runbook plus ownership, observability
hooks, and maintenance notes - each linked to its artifact or marked N/A with a
reason. The work is not done until that pack is whole. This is the gate that
makes the output operable and maintainable by a team that did not write it, and
it pairs with `verification-before-completion`: never assert "done" before the
pack is complete and its evidence is real, not asserted.

### Artifact standards and cross-skill composition

Every skill in this repository — baseline, specialist, or platform — must follow `skill-composition-standards`. That skill defines:

- **The house style** every SKILL.md must meet (frontmatter, required section order, ≤500 lines, decision rules as tables, concrete anti-patterns, British English, no emojis).
- **The input and output contracts** every skill declares: what artifacts it consumes from upstream, what it produces for downstream. Standard artifacts have templates — context map, ADR, critical-flow table, entity model, access patterns, migration plan, OpenAPI contract, error model, SLO set, release plan, rollback plan, runbook, threat model, test plan, and the closing Delivery Definition of Done pack.

The artifact list above in this section maps directly onto the `skill-composition-standards` templates. When a skill produces "architecture" or "release evidence", it means the template-format version, not free-form prose. This is what makes the repository compose as a system rather than a library of linked documents.

For authoring new skills or normalising older ones against the current bar, load `skill-composition-standards` first, then `skill-writing`.

## Executable Standard

### Attention-to-detail execution rule

Work in thin vertical slices that a developer can explain end to end. For each
slice, inspect the existing architecture and data flow, implement one useful
behaviour, check its normal and failure states, review the user-visible result,
and make a deliberate refinement before expanding scope. The same rule applies
to requirements, design, code, tests, documentation, and kaizen records. Do not
use a broad generated scaffold as a substitute for understanding; record the
slice, the changed decision, and the evidence that closed it.

Treat engineering as a delivery system, not only an implementation activity. A result is not world-class unless it can be changed safely, verified quickly, deployed repeatedly, diagnosed under stress, and improved without heroics.

For non-trivial work, explicitly produce or update:

- a critical-flow table: actor, trigger, happy path, failure modes, operator action
- a release path: commit stage, deeper verification, rollout method, rollback method
- a telemetry map: logs, metrics, traces, audit events, release markers
- a test strategy: risk class, required layers, manual checks, residual risk
- an ownership map: module owner, alert owner, operational escalation path
- a simplification note: what complexity was intentionally avoided and why

## Delivery Workflow

### 1. Frame the Product and Business

Before architecture, define:

- target users, operators, buyers, and internal stakeholders
- top jobs to be done and why they matter
- current pain, cost, delay, risk, or revenue friction
- what users should love about the experience if the work succeeds
- success metrics: adoption, conversion, retention, reliability, latency, support burden, margin, engineering speed

If value is unclear, the design is premature.

### 2. Create Shared Understanding

Before proposing code or architecture, define:

- Primary user journeys and failure-sensitive flows.
- Required behaviors, non-goals, edge cases, and unresolved questions.
- Scale assumptions: users, requests, data growth, concurrency, latency, offline needs.
- Trust boundaries: client, edge, API, worker, database, third parties, admin surfaces.
- Quality attributes ranked in order: correctness, security, latency, throughput, cost, operability.
- Hard constraints: platform, staffing, deadlines, compliance, legacy dependencies.

Use shared language and explicit examples. Requirements are not complete until engineering, product, design, and operations would interpret the system the same way.

State the ceremony class aloud before designing: spike, bounded or architectural. A spike answers one question with throwaway code (`product-discovery/references/question-answering-prototypes.md`); a bounded change stays inside an existing module with a known seam; an architectural change adds a module, a trust boundary or a data store.
The ratchet only goes up: hidden complexity moves a task to a higher class, and nothing moves it down. An approval covers only the stage actually presented, not the stages after it.
Where the Superpowers plugin is installed its brainstorming skill may help; this gate stays authoritative. (Ceremony ratchet adapted from obra/superpowers, MIT, https://github.com/obra/superpowers, commit 8ca22dba9a94f28898bbce59f2537ff4d87c747d.)

### 3. Design the Shape

Choose system boundaries deliberately:

- Separate product capability boundaries from technical layers.
- Design around domain concepts, workflows, policies, and invariants.
- Keep domain rules independent from transport, UI, and storage frameworks.
- Define ownership of modules, APIs, schemas, events, and shared contracts.
- Use ADR-style reasoning for important choices: context, options, tradeoffs, decision, fallout.
- Prefer explicit seams for auth, billing, feature flags, audit logs, jobs, and integrations.

### 4. Engineer for Change and Throughput

Build for future modifications:

- Small modules with high cohesion and low coupling.
- Stable interfaces around volatile dependencies.
- Backward-compatible contracts by default.
- Expand-contract data changes for live systems.
- Idempotent writes, retry-safe jobs, and deterministic side effects.
- Optimize for iteration speed where it does not compromise safety: fast tests, reversible releases, small changes, low-friction environments.
- Record decisions and assumptions so future engineers do not need to rediscover them.
- Keep work in small batches. Large changes hide risk, slow review, and reduce rollback quality.
- Keep `main` or the releasable branch deployable. If that is not true, the delivery system is degrading.
- Prefer trunk-friendly integration, short-lived branches, and feature flags over long-lived divergence.

### 5. Engineer for Failure and Operations

Assume the happy path is incomplete:

- Enumerate validation, dependency, timeout, concurrency, and partial-failure modes.
- Define user-visible fallback behavior for each critical path.
- Add logging, metrics, tracing, and audit events where diagnosis matters.
- Make recovery paths explicit: retry, replay, reconcile, compensate, roll back.
- Reduce operational burden with automation for repeatable mechanics before trying to automate judgment.
- Design ownership for alerts, incidents, follow-up fixes, and stale complexity removal.
- Add release markers and version metadata so incidents can be tied to specific changes quickly.
- Design operator workflows with stress in mind: simple commands, obvious blast radius, safe defaults, clear reversibility.

### 6. Manage Delivery as a System

World-class engineering management means:

- prioritize by expected impact, risk reduction, and learning value
- split work into reviewable, testable increments
- validate early with prototypes, experiments, staging checks, or rollout slices
- preserve team health and clarity with transparent decisions, direct communication, and explicit ownership
- build a culture where knowledge is shared, review is normal, and hidden work is discouraged
- stop the line when the build, deployment path, or telemetry becomes unreliable
- treat incidents, flaky tests, broken pipelines, and missing runbooks as delivery-system defects, not routine noise

Good management increases both throughput and quality. It does not trade one for the other by default.

### 7. Ship with Gates

Do not call an output production-ready unless it passes:

- Product-value gate
- Architecture gate
- Security gate
- Performance gate
- Reliability gate
- UX/content gate
- Testability gate
- Operability gate

Use the release gates in [references/world-class-gates.md](references/world-class-gates.md).

### 8. Learn and Simplify

- capture what slowed delivery, detection, recovery, or understanding
- remove recurring toil before adding more process
- convert useful lessons into automation, tests, runbooks, or simpler architecture
- reassess branch strategy, pipeline stages, and alerting if the team depends on heroics
- keep the feedback loop visible with deployment frequency, lead time, change failure rate, and recovery time

## Solution Selection

Before a substantive change, write the short record in [references/solution-selection.md](references/solution-selection.md): understand the existing flow, ask whether new code is needed at all, reuse the repository, prefer the standard library or platform, check installed dependencies, then choose the smallest option that keeps every requirement and safeguard. Worked cases are in [references/solution-selection-examples.md](references/solution-selection-examples.md).

Smallest never means removing a safeguard. On ERP, accounting, POS and SaaS money or authorisation paths, these are never simplified away:

- audit-trail writes;
- idempotency keys on retried or integration-driven writes;
- database constraints (keys, uniqueness, checks);
- period locks;
- segregation-of-duties checks;
- tenant scoping on every query and write;
- structured logging on money and authorisation paths;
- reconciliation records.

A proposal that drops any item above is a failed simplification, whatever it saves.

## Non-Negotiable Standards

### Product and Commercial Quality

- Solve an expensive problem, remove meaningful friction, or create a clearly superior experience.
- Make premium value visible through packaging, proof, onboarding, service design, reporting, controls, and sales assets; quality that buyers cannot inspect or understand does not support premium pricing.
- Make the core workflow easy to understand, easy to trust, and hard to misuse.
- Reduce time-to-value for first use, repeated use, and recovery from mistakes.
- Treat product quality, writing, and system behavior as one user experience.

### Engineering

- Use explicit module boundaries and predictable dependencies.
- Keep business logic out of controllers, routes, views, and UI components.
- Name things by domain meaning, not implementation detail.
- Prefer composition over inheritance unless hierarchy is truly stable.
- Document the invariants that must never be violated.
- Compare viable options before committing to a costly shape.
- Favor simple designs with known tradeoffs over fashionable architectures.

### Performance

- Define latency and throughput budgets before optimizing.
- Measure on realistic devices, networks, data volumes, and concurrency.
- Eliminate unbounded work on request paths.
- Budget memory, bundle size, query cost, background work, and third-party dependencies.
- Optimize the highest-impact user path first.

### Security

- Model abuse cases before implementation, not after.
- Deny by default.
- Scope every data access by actor, tenant, and permission.
- Validate input at every boundary and encode output for its destination.
- Protect secrets, tokens, keys, sessions, webhooks, and admin operations with dedicated controls.

### Reliability and Operability

- Design retries, timeouts, backpressure, and degradation deliberately.
- Assume duplicate delivery, partial writes, stale reads, and dependency slowness will happen.
- Every critical workflow needs diagnosis signals, recovery steps, and ownership.
- Make incident response easier through correlation IDs, safe defaults, and documented runbooks.

### UX and Product Writing

- Reduce cognitive load before adding new features.
- Use conventions unless deviation clearly improves outcomes.
- Write microcopy that explains action, consequence, and recovery.
- Treat loading, empty, error, and success states as first-class design work.
- Design for accessibility, translation expansion, and interruption recovery.

### Management and Team Execution

- Prioritize work by leverage, not visibility.
- Invest in learning, documentation, and reusable systems that compound over time.
- Keep decision-making transparent enough that other engineers can contribute early.
- Delegate ownership, not just tasks.
- Build psychological safety for review, correction, and escalation.

### Developer Workflow

- Keep branches short-lived and commits reviewable.
- Make CI prove correctness, safety, and packaging readiness.
- Build artifacts once and promote the same artifact through environments.
- Use code review to catch risk, not style trivia.
- Preserve deployability on main.
- Favor feature flags, dark launches, or canary-style exposure when risk is hard to remove upfront.
- Make rollback and release verification routine, not heroic.

## Delivery-System Heuristics

- If the change cannot be released safely in isolation, shrink it or add a release-control mechanism.
- If production confidence depends on a person remembering manual steps, encode those steps into the delivery workflow.
- If a rollback depends on deleting or rewriting live data, the release design is too fragile.
- If observability cannot explain a failure inside the first few minutes, the system is under-instrumented.
- If tests are slow, flaky, or hard to trust, they are limiting throughput and must be treated as product defects in the engineering system.
- If architecture decisions increase cognitive load without clear gains in deployability, reliability, or ownership, simplify.

## Review Prompts

Use these prompts while working:

- What must stay true even under load, retries, and partial failure?
- What becomes expensive or unsafe at 10x current scale?
- Which decisions are hard to reverse later?
- What will the next engineer misunderstand here?
- What evidence shows users and the business actually benefit from this work?
- What part of the workflow will become a tax on the team six months from now?
- What evidence proves this is ready beyond "it works on my machine"?

## Companion Skills

- Load `system-architecture-design` for decomposition, ADRs, and tradeoff analysis.
- Load `database-design-engineering` for schemas, queries, migrations, and data lifecycle choices.
- Load `git-collaboration-workflow` for branch, review, and release discipline.
- Load `saas-erp-system-design` for configurable business systems, auditability, and domain boundaries.
- Load `observability-monitoring` for telemetry, SLOs, alerts, and diagnosis-first dashboards.
- Load `reliability-engineering` for fault tolerance, incident readiness, and recovery-aware design.
- Load `advanced-testing-strategy` for risk-based validation and release evidence.
- Load `deployment-release-engineering` for rollout, rollback, migration-safe shipping, and post-deploy verification.
- Load `distributed-systems-patterns` when crossing service, queue, or consistency boundaries.
- Apply this skill's engineering-management guidance for delivery operating rhythm, delegation, communication, and team scaling (the retired `engineering-management-system` skill is an inactive alias of it).
- Load platform and security skills relevant to the stack after this baseline is established.
- Load `validation-contract` when authoring a specialist skill or assembling a Release Evidence Bundle for ship; it is the canonical source for what evidence ship readiness requires.
- Load `premium-software-product-execution` when the software itself must support premium pricing, executive trust, sales enablement, website/content authority, or refusal of commodity work.

## References

- [references/source-patterns.md](references/source-patterns.md): Book-to-practice workflows derived from the supplied PDFs.
- [references/executable-engineering-system.md](references/executable-engineering-system.md): Delivery-system rules, artifacts, and operating loops derived from the supplied books.
- [references/world-class-gates.md](references/world-class-gates.md): Release gates for engineering, security, performance, UX, and operations.
- [references/verification-loop.md](references/verification-loop.md): Per-change six-phase completion gate and report format.
- [references/quality-bar-guard.md](references/quality-bar-guard.md): Write the project quality bar once, place checks by cost, guard diffs against weakening, ratchet upwards only.

## Inputs

| Artefact | Required? | Purpose |
|---|---|---|
| Change scope and acceptance criteria | yes | Define the quality target |
| Architecture and risk context | yes | Select applicable gates |
| Existing tests and operational evidence | conditional | Establish current readiness |

## Capability contract

Require read and search. Editing and execution follow the implementation scope. Without execution, label checks unverified and return the commands or evidence still required.

## Decision rules

| Risk | Gate depth | Failure avoided |
|---|---|---|
| Local, reversible, no data or auth effect | Focused checks | Process overhead without risk reduction |
| Cross-module, data, auth, or deployment effect | Full evidence pack | Hidden integration or rollback gaps |
| Production mutation or irreversible action | Explicit approval and rollback proof | Unbounded blast radius |

## Domain anti-patterns

- Applying every gate to a trivial local edit. Fix: scale evidence to risk.
- Skipping rollback because tests pass. Fix: prove recovery for deployment-affecting work.
- Treating a checklist tick as evidence. Fix: link the command result or artefact.
- Optimising one quality attribute while hiding another regression. Fix: record trade-offs.
- Declaring production-ready with unverified checks. Fix: label gaps and block when material.
## Outputs
- Produce the risk-scaled engineering gate, evidence pack, release verdict, and residual-risk handoff.
## Degraded mode
Fallback without execution or operational evidence: issue a conditional verdict, list unverified gates, and block release when a material risk cannot be assessed.