engineering-quality

Engineering quality

Purpose

Keep code understandable under change. This skill supplies the maintainability contract; the implementation skill owns production edits and the test skill owns behavioral proof.

Change context

• Read the request, affected code, tests, and local conventions.
• Identify the behavior that must remain stable and the specific maintenance problem being solved.
• Separate observed problems from stylistic preference.
• Read references/engineering-quality.md for the decision criteria.

Change method

1. Map the changed responsibilities, dependencies, side effects, and public contracts.
2. Find the smallest structural issue that affects correctness, readability, testability, or future change cost.
3. Prefer a local correction: clearer name, smaller responsibility, explicit dependency, simpler control flow, stronger boundary, or removal of proven duplication.
4. Reject abstractions that only prepare for hypothetical reuse.
5. Preserve behavior with the affected test suite. When behavior changes, require an acceptance criterion and regression test.
6. Check errors, logs, and comments from the caller's point of view.
7. Report any wider debt separately instead of expanding the patch.

Evidence

• The maintenance problem and its concrete impact
• The narrowest useful change or review finding
• Behavior-preservation evidence
• Any compatibility, migration, or rollback concern
• Deferred debt that remains outside scope

Ready when

• Names and structure express the domain without explanatory noise.
• Responsibilities and dependencies are visible at the right boundary.
• Side effects and failure behavior are explicit.
• Tests describe behavior rather than mirror the implementation.
• The patch contains no unrelated cleanup.
• Performance claims are measured, not assumed.

Handoff

Pass the scoped recommendation to service-implementation, or report findings through pr-review. Include the exact tests that protect the behavior.