system-boundary-review

name

system-boundary-review

description

Boundary-aware design and change review for the Lux repo. Use when a task might create/change a boundary (CLI commands/flags, on-disk artifacts or schema formats, cross-component APIs, "public" internal interfaces, dependency direction changes, versioning/backcompat decisions) or when you're unsure what the boundary is. Output a concise Boundary Review plus candidate repo boundary rules to discuss.

System Boundary Review

Overview

Identify boundaries early, design their contracts deliberately, and avoid locking in leaky or tightly-coupled interfaces.

Workflow

1) Decide: Is This a Boundary?

Treat it as a boundary if any are true:

• External user or "can't break it easily" constraint exists (real or simulated).
• It is a versioned or durable surface: CLI UX, file formats, schemas, API routes, library interfaces, wire protocols.
• Many internal call sites depend on it (even if you control them).
• It crosses an ownership/team/component boundary, or is intended for reuse.

If it is not a boundary, proceed with normal refactoring discipline; still prefer small interfaces, but optimization pressure is lower.

2) Name the Contract

Write down (in the PR/spec notes):

• Producer and consumers.
• What makes it hard to change (upgrade constraints, external users, data already written, etc.).
• What is explicitly NOT promised.
• Stability target: experimental vs stable vs "public".

3) Shape the Boundary (Avoid Leaks)

Design inputs/outputs around the minimal information needed for the consumer use cases.

• Prefer passing the specific fields you need over passing whole "domain objects" (avoid information leaks).
• Avoid "debug" fields/flags/params that expose producer internals; they get depended upon.
• Avoid boolean-flag APIs at boundaries; name operations and concepts instead.
• Prefer fewer dependencies: the most important thing is what the boundary does NOT depend on.

4) Check Dependency Direction and Ownership

For the proposed contract:

• Verify dependency direction matches the intended layering.
• Ensure the consumer does not need to know producer implementation details.
• If a refactor redraws boundaries, call out migration cost and expected unforeseen consequences.

5) Versioning / Backwards Compatibility

If the boundary is durable (CLI/schema/artifact formats/APIs):

• Decide whether to version (and how).
• Decide how to deprecate: timeline, migration plan, compatibility shims.
• Prefer adding new surface area over breaking existing callers unless the break is justified and planned.

6) Produce the "Boundary Review" Output

Add a short section to the work product (spec/PR description) using this template:

## Boundary Review
- Boundary surface(s):
- Producer / consumers:
- Why it's a boundary (what makes it hard to change):
- Contract proposed (inputs/outputs, promises, non-promises):
- Potential information leaks / coupling risks:
- Dependency direction / layering notes:
- Versioning / migration plan (if applicable):
- Alternatives considered:

If the user is trying to define repo boundary rules, also output:

## Candidate Repo Boundary Rules (Draft)
1. ...

Deep References (Load Only If Needed)

Use these repo notes when you need more detail or examples:

• docs/research/system_boundaries/boundary-drawing.md (boundaries are invented; reconsider deliberately; redrawing is costly)
• docs/research/system_boundaries/system_boundariees_the_focus_of_design.md (what makes a boundary; why rules differ at boundaries; boundaries are not free)
• docs/research/system_boundaries/good-software-architectures-are-mostly-about-boundaries.md (boundaries as contracts; information leaks; examples of "debug" surface area becoming dependency)

Notes

• This skill is intended for use inside this repo; references assume the repo workspace is available.
• Do not turn draft "boundary rules" into normative repo contracts without explicit user approval; propose, discuss, then encode in docs/spec/tests.