BuzzbeeSCD/openchamber
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: refine agent skill guidance

Browse Source
This commit is contained in:
Bohdan Triapitsyn
2026-08-13 13:57:56 +03:00
parent d3011a6247
commit cc94c3c927
15 changed files with 212 additions and 248 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.agents/skills/openchamber-change-discipline/SKILL.md
+12 -36
View File
@@ -9,15 +9,11 @@ description: Use when implementing, fixing, refactoring, or otherwise modifying
Make the smallest complete change and validate at the narrowest level that covers the real risk.
Identify existing behavior covered by tests or callers; preserve it unless the requested change explicitly replaces it.
## Before Editing
1. Read the nearest `DOCUMENTATION.md` and package `README.md` when present.
2. Inspect nearby implementation and tests before introducing a pattern.
3. Load every additional project skill whose trigger matches the change.
4. Classify the highest applicable change risk below.
5. Identify affected consumers, runtimes, persisted data, and public exports.
1. Inspect nearby implementation, callers, and tests before introducing a pattern.
2. Classify every applicable change risk below.
3. Identify every affected consumer, runtime, persisted format, and public export. This step is complete only when each risk has an owner and required validation.
When instructions materially conflict, stop and resolve the conflict instead of silently choosing one.
@@ -33,30 +29,23 @@ When instructions materially conflict, stop and resolve the conflict instead of
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.
## Mandatory Rules
## Structural Discipline
- Identify existing behavior covered by tests or callers; preserve it unless explicitly replaced.
- Do not add dependencies unless explicitly requested.
- Do not add compatibility paths without a concrete persisted or external consumer.
- Enforce security and correctness in core logic, not only UI controls or prompts.
- Never add, persist, or log secrets, bearer tokens, pairing data, or sensitive user content.
- Make data loss, partial failure, rollback, and fallback behavior explicit.
- Update owning documentation when module ownership, contracts, or invariants change.
- Complete the cumulative validation required by every applicable risk category.
## Engineering Preferences
- Prefer the smallest correct change; avoid drive-by refactors.
- Keep orchestration entrypoints thin and move domain logic to focused modules.
- 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.
- Prefer early returns and explicit branches over nested conditionals.
- 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.
- Make partial failure, rollback, cleanup, and user-visible outcomes explicit for destructive or multi-step work.
## 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?
@@ -75,8 +64,6 @@ Do not hide a required architectural migration behind a local heuristic. Do not
## Validation Matrix
Use `package.json` scripts as the command source of truth.
| Change | Minimum validation |
|---|---|
| Executable source | Focused tests plus package-scoped type-check and lint |
@@ -108,15 +95,4 @@ For type-only shared contracts, validate compile-time consumers. Add runtime ser
- Run focused regression tests for the changed contract.
- Preserve unrelated changes encountered in shared files.
- Re-read the owning docs and update them when the implementation changed their truth.
- Do not claim runtime, relay, performance, or platform correctness from type-check/lint alone.
## Common Failure Modes
| Failure | Correction |
|---|---|
| Refactoring nearby code while fixing one bug | Keep the diff scoped unless the nearby change is required |
| Adding a helper used once | Keep direct code until reuse or composability is real |
| Swallowing an error for smoother UX | Preserve the failure signal and handle presentation separately |
| Updating a bridge without all runtimes | Load the runtime/API skill and make parity explicit |
| Running only broad checks | Add focused tests that exercise the changed behavior |
| Running only focused checks after a shared-contract change | Add workspace-wide validation |
- Perform a final simplification pass: remove speculative branches, shallow wrappers, stale compatibility, and names that do not clarify intent.