Code Clarity Maintainability

code-clarity-maintainability

Registry Trigger

Use when

• Changed main or exceptional flow is hard to trace because branches, helpers, comments, or simplification obscure outcomes, cleanup, cancellation, or side effects.
• Naming, conditions, split/merge navigation, or test readability makes the owning rule, next change, or deletion path ambiguous.

Do not use when

• The unresolved decision is file, object, module, signature, or public-contract placement; use the owning structure or API capability.
• The work is behavior-preserving movement, language-specific semantics, or runtime performance with no remaining clarity decision.

Skill Role

Make changed behavior and obligations traceable from its public entry point. Exclude placement, module/API ownership, language semantics, runtime safety, and behavior-preserving movement.

High-Value Rules

• Trace the affected entry point to each material terminal outcome. Validation, denial, fallback, retry, cancellation, cleanup, and response obligations stay visible where they can alter the result.
• When changing guards, extraction, inlining, or branch shape, verify evaluation order, short-circuiting, resource release, cancellation, and visible side-effect order.
• Names distinguish semantic role, state, unit, authority, and failure meaning; they do not turn a domain rule or public failure into a vague helper or mode.
• Extract or name a condition when it separates an owned decision; keep direct code when extraction would hide effects, introduce indirection, or split one cohesive obligation.
• Comments record non-obvious contract, invariant, compatibility, or operational reason; tests assert public behavior and the regression mechanism rather than private call shape.
• Use complexity, length, and file-count signals to select inspection scope; approve only from traceability and preserved obligations, not a generic threshold.
• A split or merge preserves a discoverable entry point, one owner per decision, visible public/test/effect boundaries, and an obvious location for the next related change or deletion.

Anti-Patterns

• A guard or early return bypasses cleanup, audit, rollback, or response work.
• A boolean, mode, negated condition, or magic value hides authority or state semantics at the call site.
• Tiny helpers or files force traversal across vague wrappers to understand one decision.
• A shorter diff or lower metric is treated as clarity proof while behavior, ownership, or test intent becomes harder to see.

Stop Conditions

• Route placement or public-contract ownership to implementation-structure-design, module-boundary-design, or the relevant API capability.
• Route behavior-preserving movement to refactoring, language semantics to language-idiom-enforcement, and runtime cost or safety to language-performance-safety.

Output Contract

• code-clarity decision with obscured path preserved obligations selected move rejected simplification public-behavior proof evidence limits and residual risk

Targeted References