OpenChamber Change Discipline

Core Principle

Make the smallest complete change and validate at the narrowest level that covers the real risk.

Before Editing

1. Classify every applicable change risk below.
2. Identify every affected consumer, runtime, persisted format, and public export. This step is complete only when each risk has an owner and required validation.

Risk Classification

Apply every matching category. Do not escalate local work into workspace-wide ritual, and do not treat a type-only export as local merely because it emits no JavaScript.

Structural Discipline

• Preserve behavior established by callers and tests unless the request replaces it. Keep the diff scoped to the complete requested behavior.
• Make the normal use-case path read top to bottom in domain terms. Keep orchestration entrypoints thin and move mechanics or domain logic behind focused, intention-revealing boundaries.
• Pull complexity downward only when a boundary hides meaningful mechanics, owns an invariant, isolates a proven integration, or captures stable repetition. Do not spread obvious code across pass-through layers.
• Prefer explicit dependencies and dependency injection over hidden module coupling.
• Follow local TypeScript types; avoid any, blind casts, and guessed payload shapes.
• Reject invalid inputs and broken preconditions early so the valid path stays flat. Do not force a numeric happy-path/error-path ratio when correctness requires substantial failure handling.
• Require evidence before adding retries, caches, compatibility paths, lifecycle machinery, or generalized race handling. Security, data-loss, destructive-operation, and concurrency invariants still require proactive design when the risk is inherent to the operation.

Review Prompts

Before broadening a change, ask:

• Is the new abstraction reused or merely possible to reuse?
• What concrete complexity, invariant, stable repetition, or boundary does each new helper, interface, layer, and file pay for?
• Is the code in the package that owns the behavior?
• Does the change alter shared UI contracts across web, desktop, VS Code, or mobile?
• Does it change persisted data, IDs, routes, exports, generated files, or package entrypoints?
• Can failure leave optimistic state, caches, files, or remote state stranded?

For partial or destructive flows, answer explicitly:

• What remains valid after the first failure?
• What is rolled back or cleaned up?
• What can be retried or resumed safely?
• What does the user observe?

For persisted data, require a migration only when existing stored data needs conversion. Test downgrade compatibility only when older application versions are a concrete supported consumer. "Rollback" means preserving/restoring valid state after a failed write or migration unless a broader contract explicitly says otherwise.

Do not hide a required architectural migration behind a local heuristic. Do not turn a local fix into a speculative rewrite.

Answering Review Findings

When a reviewer (a subagent, a review session, a bot) reports on your change, you own the change and the reviewer advises. Review loops grow a change one cheap-looking fix at a time; hold it at the size its goal needs.

• Weigh every finding yourself before acting. A problem the change neither causes nor set out to fix (another path, a rare case, a small cost that was there before) is a nit, whatever label it came with. A regression this change introduces is never a nit, however rare its case.
• Fix what is wrong in the case the change is for, with the smallest fix. A fix that deletes or narrows code beats a new guard, helper, option, or test the goal does not need.
• A finding you think is wrong stays unfixed, with evidence: file and line, a test, command output. Decline nits and out-of-scope items in one line each; a real problem outside the change goes to the report as a follow-up.
• Never agree with a finding just to end the review.
• A finding still disputed after you and the reviewer have each answered twice goes to the maintainer, with both positions in two or three lines each. Do not argue a third round.
• After the fixes, compare the diff size with the one before review. If review grew it, cut first.

Validation Matrix

bun run check:changed is the pre-commit gate: run it once, right before a commit, on the finished diff. While iterating, run only the focused tests for the behavior you just changed; an edit to docs, comments, or strings needs no check at all.

When several agents edit one checkout in parallel, they edit and run single test files only. The coordinator runs type-check, lint, builds and full suites once, serially, on the combined diff: each type-check holds over a gigabyte, parallel copies have frozen the machine, and a check run mid-edit reports the other agents' half-finished work.

Use a sufficiently long timeout for broad checks.

For type-only shared contracts, validate compile-time consumers. Add runtime serialization tests when the contract crosses a process, persistence, network, or untyped JavaScript boundary.

Proof

A test is proof when it is deterministic and fails without the change: a pure function, a page script, a reducer. Behavior that lives in a runtime is proven by running that runtime and watching the scenario; a test there that only mirrors the implementation through mocks or races real timers adds upkeep and flakes, and the run already shows more.

Pick the scenarios before counting them. First run the plain path a user takes, end to end in the running app; then break it the ordinary ways it breaks: a credential the server stops accepting, a server that is down, a sign-in the user cancels or that fails, an empty or slow answer. Look at what the user sees each time. These ordinary breaks are where shipped bugs sit, so they come before rare races and exotic inputs, which earn coverage only with a concrete reason. Tests then pin what the runs found.

Where to run it

Run the scenario in the runtime that executes the changed code. Every route below starts its own instance on free ports, beside the user's own app and dev servers.

Use localhost, never 127.0.0.1, for the web server: the desktop app lifts Chromium's connection cap for 127.0.0.1, and the panel then overruns Vite and resets connections. Build the desktop app only for a change that lives in its shell. Stop each instance by its own process id or process group, never by a name pattern that would stop someone else's.

The panel's browser actions run in the app the agent itself works from, so they cannot reach a change to the panel's own code until that app is rebuilt; the electron:dev route above covers it before.

Test Design

• Prefer observable contracts, state transitions, failure handling, rollback, and operation counts.
• Test private helpers through public/module behavior when that captures the risk clearly.
• Assert internal map shape, helper calls, or call order only when that structure/order is itself a contract.
• Keep refactor tests resilient to equivalent internal implementations.
• For behavior-preserving refactors, establish the current behavior before changing structure.

Module Documentation

A module's DOCUMENTATION.md lives in its folder and holds what the code cannot show the next agent: what the module owns, what must stay true, and why it is built this way. A module gets its own document when it owns a contract other code relies on, an invariant, or a non-obvious design choice; a folder without any of these is covered by its parent's document.

The document has three parts:

• Ownership. What the module owns and where its boundary is: what belongs here and which neighbouring module owns the rest.
• Invariants. What must stay true, each stated so a change can be checked against it.
• Decisions. One ### Why X and not Y entry per non-obvious choice: the chosen approach, the alternative it was weighed against or replaced, and the reason in one or two sentences. A choice is non-obvious when a later reader could reasonably "fix" it back: a simpler design that was rejected, a deliberate workaround, a measured trade-off.

The document describes the module as it is now. When a decision changes, rewrite its entry around the new choice and keep the old approach as the rejected alternative, so the file stays current and carries no history to unwind. Spend its lines on reasons and contracts; file listings and function-by-function walkthroughs restate the code and go stale first.

Completion Standard

• Implement the behavior end to end, including rollback and cleanup.
• Prove the changed behavior (Proof): the reproduction passes, and the report says what the proof did not cover.
• Preserve unrelated changes encountered in shared files.
• The owning DOCUMENTATION.md is true of the new code and has a decision entry for every non-obvious choice the change made; a new module that meets the bar in Module Documentation has its own document.
• Perform a final simplification pass over your own diff, hardest after a rework or a removal: every branch, condition, prop, parameter, export, key, and helper the change made unreachable, always-true, or single-valued is gone, along with speculative branches, shallow wrappers, stale compatibility, and names that do not clarify intent.