MCAF: SOLID Maintainability

Trigger On

• files, classes, or functions are too large or too coupled
• maintainability limits in AGENTS.md need to be added or tightened
• a change needs a justified temporary exception

Value

• produce a concrete project delta: code, docs, config, tests, CI, or review artifact
• reduce ambiguity through explicit planning, verification, and final validation skills
• leave reusable project context so future tasks are faster and safer

Do Not Use For

• writing architecture docs without touching code structure or policy
• cosmetic formatting-only edits

Inputs

• the nearest AGENTS.md
• the code under change
• current testing seams and dependency boundaries

Quick Start

1. Read the nearest AGENTS.md and confirm scope and constraints.
2. Run this skill's Workflow through the Ralph Loop until outcomes are acceptable.
3. Return the Required Result Format with concrete artifacts and verification evidence.

Workflow

1. Read the active values for:
   • file_max_loc
   • type_max_loc
   • function_max_loc
   • max_nesting_depth
   • exception_policy
2. Evaluate the change through SOLID:
   • single responsibility
   • explicit dependencies
   • composition before inheritance
   • boundaries that are easy to test
3. Remove hardcoded values and inline string literals from implementation code by moving them into named constants, enums, configuration, or dedicated types.
4. Split by responsibility, not by arbitrary line count alone.
5. If a limit must be exceeded temporarily, document the exception exactly where exception_policy requires it.

Deliver

• smaller, more cohesive code
• updated maintainability policy when repo rules changed
• explicit exception records when a temporary breach is justified

Validate

• size limits are respected or explicitly waived
• responsibilities are clearer after the change
• the refactor improves testability instead of only moving lines around
• literals that matter are named once and reused instead of repeated inline
• no numeric limit was moved into framework prose or skill metadata

Ralph Loop

Use the Ralph Loop for every task, including docs, architecture, testing, and tooling work.

1. Brainstorm first (mandatory):
   • analyze current state
   • define the problem, target outcome, constraints, and risks
   • generate options and think through trade-offs before committing
   • capture the recommended direction and open questions
2. Plan second (mandatory):
   • write a detailed execution plan from the chosen direction
   • list final validation skills to run at the end, with order and reason
3. Execute one planned step and produce a concrete delta.
4. Review the result and capture findings with actionable next fixes.
5. Apply fixes in small batches and rerun the relevant checks or review steps.
6. Update the plan after each iteration.
7. Repeat until outcomes are acceptable or only explicit exceptions remain.
8. If a dependency is missing, bootstrap it or return status: not_applicable with explicit reason and fallback path.

Required Result Format

• status: complete | clean | improved | configured | not_applicable | blocked
• plan: concise plan and current iteration step
• actions_taken: concrete changes made
• validation_skills: final skills run, or skipped with reasons
• verification: commands, checks, or review evidence summary
• remaining: top unresolved items or none

For setup-only requests with no execution, return status: configured and exact next commands.

Load References

• read references/limits-and-exceptions.md first
• open references/maintainability.md for broader design guidance
• open references/exception-handling.md when documenting a temporary breach

Example Requests

• "Split this 700-line service into cohesive parts."
• "Add maintainability limits to AGENTS."
• "Refactor this class to follow SOLID and document the one exception."

Guardrails

• numeric limits belong in AGENTS.md, not in the framework guide or skill metadata
• a justified exception is a debt record, not a permanent escape hatch