write-maintainable-code

Write maintainable code

Use the fewest concepts that satisfy the approved result and its acceptance evidence. Minimize maintenance burden, not raw line count.

Keep the ownership boundary

• reasoning-doctrine owns the stage, outcome, scope, evidence, route recommendation, hard stops, and the transition to execution.
• governed-operator owns authority, seats, formal contracts, verdicts, publication, and Done.
• This skill owns route comparison, ownership seams, concept control, readability, and implementation verification.

If outcome, acceptance evidence, or authority is unresolved, return to its owner. Apply this lens only to the selected route and safe slice. A finished change needs independent review.

Compare routes before adding code

1. Restate the fixed result and acceptance evidence without reopening them.
2. Inspect current behavior, configuration, reuse, deletion, documentation, and no-code routes. If the current evidence already passes, make no change.
3. Choose a route only when the fixed acceptance evidence can prove it.
4. Name the smallest ownership seam and the concepts the selected route needs. Name tempting concepts the result does not need.

When routes satisfy different checks and the current evidence does not identify the applicable check, return that gap to whoever owns the outcome and acceptance evidence. Do not create a second implementation brief or return schema.

Bound the implementation

Decline a dependency, layer, abstraction, state, endpoint, migration, generic helper, or compatibility path whose only reason is hypothetical reuse or an unselected future. Prefer readable, explicit, testable code over dense code. A longer implementation is smaller when it carries fewer concepts or less maintenance risk.

Treat file size as a signal, not a diagnosis. Extract a bounded seam only when the extraction lowers verified current risk. Remove only code made obsolete by the selected change. Report unrelated cleanup instead of doing it.