Maintainability

Maintainability

Use this helper when the main question is future edit cost.

$fw:maintainability is for structure, locality, naming, and coupling. It is not a generic style checker.

When directly invoked, always do maintainability work. Ground the current repo shape, identify concrete friction, and recommend the minimum structure that keeps later changes understandable.

Interaction Method

Follow ../references/host-interaction-contract.md.

Call the exact host question tool named in ../references/host-interaction-contract.md when that tool is available. Do not ask for raw 1/2/3 replies when the host already offers a choice surface.

Input

#$ARGUMENTS

If blank, inspect the repo for the most obvious maintainability pressure points near the target area first.

Reference Loading Map

• Read ../references/architecture-code-quality/activation-heuristics.md when deciding whether this helper is a better fit than simplify or architecture-strategy.
• Read ../references/architecture-code-quality/output-contract.md when preparing the final brief.

Core Principles

1. Future edit cost is the metric - recommend changes only when they make later modification safer or clearer.
2. Locality beats needless reuse - keep logic near its owner until a real second use or shared boundary appears.
3. Names and file placement carry architecture - unclear ownership is a maintainability issue, not mere taste.
4. Cohesion matters more than abstraction count - helpers should exist to reduce friction, not to hide it.
5. Do not widen scope casually - stay near the changed surface unless a broader structural change is truly required.

Workflow

Phase 1: Ground Current Structure

Inspect:

• ownership and file placement
• naming and module boundaries
• helper or wrapper layers
• duplicate or parallel control flow
• tests that reveal likely future edit paths

Phase 2: Identify Real Friction

Call out concrete maintainability risks such as:

• unclear ownership
• duplicated behavior that must stay in sync
• coupling across unrelated modules
• helper extraction that made the main path harder to follow
• naming that hides intent or domain meaning

Phase 3: Recommend The Smallest Useful Cleanup

Prefer:

• keeping logic local
• collapsing unnecessary wrappers
• clarifying names or ownership
• extracting only the helper that clearly reduces repetition or boundary noise

Output Contract

Return a concise maintainability brief:

1. Current truth — how the repo currently structures this area
2. Main maintainability risks — concrete future-edit costs
3. Recommendation — the smallest structural change that helps
4. What not to add — abstractions or moves that would increase carrying cost
5. Verification hooks — tests, review angles, or follow-up checks
6. Next move — which Flywheel stage should act on the guidance