---
name: engineering-collaboration
description: >-
  Use only when a request asks to implement, modify, refactor, or review code: follow local conventions, narrow broad or dynamic types, and explain conclusions clearly. Do not use for standalone design or architecture advice, operations-only diagnosis, prose, non-software work, or raw data.
---

# Engineering Collaboration

Make technical work fit the existing repository and remain understandable to collaborators. Do not turn personal preferences into project rules, let dynamic values leak through business boundaries, or substitute jargon for explanation.

## Communication

- Lead with the outcome or current status, then explain cause, impact, evidence, and next action as needed.
- Briefly define unfamiliar terms on first use. Do not repeatedly explain terms the user already uses confidently.
- Match the user's language while preserving code symbols, protocol fields, and product names.
- Simplification must not hide assumptions, risks, failure boundaries, or uncertainty.

Read [references/communication-and-explanation.md](references/communication-and-explanation.md) only for a complex design, diagnosis, tradeoff, or long technical artifact whose explanation needs deliberate layering.

## Fit the codebase

Before editing, inspect repository instructions, formatter and linter rules, compile or type-check configuration, the maintained pattern in the affected module, and nearby code. When historical styles differ:

- follow the effective convention in the affected module;
- avoid repository-wide cleanup or unrelated formatting;
- do not introduce a third style;
- do not copy a legacy pattern that conflicts with correctness, safety, or an explicit engineering constraint;
- ask only when the choice changes a public interface, directory architecture, serialization, error semantics, or requires broad restructuring.

Read [references/codebase-conventions.md](references/codebase-conventions.md) only when legacy or mixed conventions make the effective local style unclear.

## Make types express business meaning

Keep `any`, `mixed`, `dynamic`, broad primitives, broad objects, and unstructured containers at genuine dynamic boundaries. Parse and validate them, then narrow to a DTO, union, enum, protocol, constrained generic, or domain type.

For every broad value, define the business-relevant value domain, structure, absence and empty-state semantics, coercion, defaults, validation, and serialization behavior. Then add constraints relevant to its category, such as string format, numeric unit and precision, boolean state meaning, collection ordering and uniqueness, object shape, or union discrimination. These categories are illustrative rather than exhaustive. A broad `number` is one common example, not the center of this rule.

Use runtime validation and contract-local documentation when the type system cannot express the constraint. Apply only dimensions that affect the contract or risk; do not manufacture exhaustive wrappers or rules for values whose meaning is already clear.

Read [references/type-semantics.md](references/type-semantics.md) only when dynamic input, broad or ambiguous values, public data structures, or domain documentation materially affect the task.

## Scope

This skill does not authorize unrelated refactoring or contract changes. More specialized skills govern production operation, database contracts, language architecture, and security; this skill only adds codebase fit, type clarity, and understandable delivery.