Refactor a specified method to reduce cognitive complexity to a requested threshold or below by extracting focused helper methods while preserving behavior. Use when the user asks to reduce method complexity, simplify nested conditionals, split large if-else or switch chains, extract validation or type-specific handlers, and verify tests show failed=0.
Reduce a named method's cognitive complexity to the requested threshold by extracting cohesive helper methods, simplifying control flow, preserving all behavior and error handling, then compiling and verifying related tests explicitly report failed=0.
When to invoke
"Refactor this method to reduce cognitive complexity below 15."
"Extract helpers from ${input:methodName} until complexity is under ${input:complexityThreshold}."
"Simplify this nested if-else chain without changing behavior."
"Reduce method complexity and verify tests show failed=0."
Inputs
Use $ARGUMENTS as the method name and target complexity threshold. Accept the legacy placeholders ${input:methodName} and ${input:complexityThreshold} when they appear in user-provided text, but resolve them to concrete values before editing. If either value is missing, infer from the selected code or ask for only the missing value.
Complexity reduction criteria
Inspect the target method for these complexity sources before editing:
Source
Refactoring move
Deeply nested if/else blocks
Replace with guard clauses or extract branch handlers.
Long switch or type dispatch
Extract case-specific methods or strategy-like handlers.
Repeated validation
Extract Validate* helpers that preserve exception types and messages.
Complex boolean expressions
Extract predicate methods with names that explain the condition.
Loops with inner conditions
Extract loop body or filtering predicates.
Repeated transformations
Extract reusable conversion or mapping helpers.
The main method should read as a high-level flow after refactoring. Helpers should have a single responsibility and use appropriate access levels such as private, private static, or async when matching the original language and project style.
Procedure
Validation is CRITICAL: tests are FAILED unless the summary proves zero failures. It is MANDATORY that related tests MUST be checked; NEVER assume pass/fail status without reading the output.
Locate ${input:methodName} and establish the baseline cognitive complexity if tooling is available.
Extract helper methods before rewriting the main flow, keeping helpers close to where they are used.
Simplify the main method with guard clauses, smaller orchestration calls, or switch expressions/statements where appropriate for the language and project.
Preserve input/output behavior, validation, exception types, exception messages, null handling, empty collection behavior, ordering, and side effects.
Compile with the project's existing build command or smallest available compile check.
Run related existing tests.
Read the test output summary and explicitly verify it contains failed=0, pass/fail counts, or the framework's exact zero-failure equivalent.
If failures appear, analyze each failure, fix the refactor, rerun tests, and repeat until zero failures.
Re-check cognitive complexity and confirm it is at or below ${input:complexityThreshold}.
Implementation rules
Rule
Required behavior
Helper scope
Make helpers static only when they do not need instance state.
Parameter passing
Pass required values explicitly; do not add shared mutable state to avoid parameters.
Return values
Use tuples or small result objects only when they clarify multiple outputs and fit project conventions.
Local variables
Avoid unnecessary locals introduced only by extraction.
Error handling
Preserve original exception types and messages unless tests or user request demand a change.
Test repair
If tests fail, assume the refactor changed behavior until proven otherwise.
Gotchas
Running tests is not verification: inspect the actual summary and confirm failed=0; do not infer success from command exit alone.
Null and empty collections break easily: compare original guard behavior before extracting predicates.
Exception messages are behavior: preserving type but changing message can still break callers or tests.
Complexity tools differ: if no analyzer is available, report the structural changes and the closest available evidence.
Output template
## Complexity refactor result
**Status:** complete | tests failing | blocked
**Method:** <methodName>
**Target complexity:** <complexityThreshold>
**Final complexity:** <value or "not measured">
### Refactoring summary
- <helper extracted and responsibility>
- <control-flow simplification>
### Validation
- Compile: pass | fail | not available — <evidence>
- Tests: pass | fail | not run — <command and summary containing failed=0>
- Behavior notes: <preserved validation/error/null behavior>
Quality gate
The method name and complexity threshold were resolved from $ARGUMENTS, placeholders, selection, or user input.
Complexity sources were identified before extraction.
Extracted helpers are focused, named by responsibility, and use appropriate access levels.
Original functionality, validation, error handling, exception types, and exception messages are preserved.
Code compiles without errors.
Existing related tests were run and the output was read to verify failed=0.
Any failed tests were analyzed, fixed, and rerun until zero failures.
Cognitive complexity is at or below the target threshold, or the inability to measure is explicitly reported.
The output follows ## Output template exactly.
1---2name: refactor-method-complexity-reduce-23description: Refactor a specified method to reduce cognitive complexity to a requested threshold or below by extracting focused helper methods while preserving behavior. Use when the user asks to reduce method complexity, simplify nested conditionals, split large if-else or switch chains, extract validation or type-specific handlers, and verify tests show failed=0.4---56# Refactor method complexity reduce78Reduce a named method's cognitive complexity to the requested threshold by extracting cohesive helper methods, simplifying control flow, preserving all behavior and error handling, then compiling and verifying related tests explicitly report `failed=0`.910## When to invoke1112- "Refactor this method to reduce cognitive complexity below 15."13- "Extract helpers from `${input:methodName}` until complexity is under `${input:complexityThreshold}`."14- "Simplify this nested if-else chain without changing behavior."15- "Reduce method complexity and verify tests show failed=0."1617## Inputs1819Use `$ARGUMENTS` as the method name and target complexity threshold. Accept the legacy placeholders `${input:methodName}` and `${input:complexityThreshold}` when they appear in user-provided text, but resolve them to concrete values before editing. If either value is missing, infer from the selected code or ask for only the missing value.2021## Complexity reduction criteria2223Inspect the target method for these complexity sources before editing:2425| Source | Refactoring move |26| --- | --- |27| Deeply nested `if`/`else` blocks | Replace with guard clauses or extract branch handlers. |28| Long `switch` or type dispatch | Extract case-specific methods or strategy-like handlers. |29| Repeated validation | Extract `Validate*` helpers that preserve exception types and messages. |30| Complex boolean expressions | Extract predicate methods with names that explain the condition. |31| Loops with inner conditions | Extract loop body or filtering predicates. |32| Repeated transformations | Extract reusable conversion or mapping helpers. |3334The main method should read as a high-level flow after refactoring. Helpers should have a single responsibility and use appropriate access levels such as `private`, `private static`, or `async` when matching the original language and project style.3536## Procedure3738Validation is `CRITICAL`: tests are `FAILED` unless the summary proves zero failures. It is `MANDATORY` that related tests `MUST` be checked; `NEVER` assume pass/fail status without reading the output.3940411. Locate `${input:methodName}` and establish the baseline cognitive complexity if tooling is available.422. Identify extraction opportunities: validation, type-specific processing, transformations, calculations, repeated code, and complex predicates.433. Extract helper methods before rewriting the main flow, keeping helpers close to where they are used.444. Simplify the main method with guard clauses, smaller orchestration calls, or switch expressions/statements where appropriate for the language and project.455. Preserve input/output behavior, validation, exception types, exception messages, null handling, empty collection behavior, ordering, and side effects.466. Compile with the project's existing build command or smallest available compile check.477. Run related existing tests.488. Read the test output summary and explicitly verify it contains `failed=0`, `pass/fail` counts, or the framework's exact zero-failure equivalent.499. If failures appear, analyze each failure, fix the refactor, rerun tests, and repeat until zero failures.5010. Re-check cognitive complexity and confirm it is at or below `${input:complexityThreshold}`.5152## Implementation rules5354| Rule | Required behavior |55| --- | --- |56| Helper scope | Make helpers `static` only when they do not need instance state. |57| Parameter passing | Pass required values explicitly; do not add shared mutable state to avoid parameters. |58| Return values | Use tuples or small result objects only when they clarify multiple outputs and fit project conventions. |59| Local variables | Avoid unnecessary locals introduced only by extraction. |60| Error handling | Preserve original exception types and messages unless tests or user request demand a change. |61| Test repair | If tests fail, assume the refactor changed behavior until proven otherwise. |6263## Gotchas6465- **Running tests is not verification**: inspect the actual summary and confirm `failed=0`; do not infer success from command exit alone.66- **Null and empty collections break easily**: compare original guard behavior before extracting predicates.67- **Exception messages are behavior**: preserving type but changing message can still break callers or tests.68- **Complexity tools differ**: if no analyzer is available, report the structural changes and the closest available evidence.6970## Output template7172```markdown73## Complexity refactor result7475**Status:** complete | tests failing | blocked76**Method:** <methodName>77**Target complexity:** <complexityThreshold>78**Final complexity:** <value or "not measured">7980### Refactoring summary81- <helper extracted and responsibility>82- <control-flow simplification>8384### Validation85- Compile: pass | fail | not available — <evidence>86- Tests: pass | fail | not run — <command and summary containing failed=0>87- Behavior notes: <preserved validation/error/null behavior>88```8990## Quality gate9192- [ ] The method name and complexity threshold were resolved from `$ARGUMENTS`, placeholders, selection, or user input.93- [ ] Complexity sources were identified before extraction.94- [ ] Extracted helpers are focused, named by responsibility, and use appropriate access levels.95- [ ] Original functionality, validation, error handling, exception types, and exception messages are preserved.96- [ ] Code compiles without errors.97- [ ] Existing related tests were run and the output was read to verify `failed=0`.98- [ ] Any failed tests were analyzed, fixed, and rerun until zero failures.99- [ ] Cognitive complexity is at or below the target threshold, or the inability to measure is explicitly reported.100- [ ] The output follows `## Output template` exactly.
Run npx skillmds@latest add paulasilvatech/refactor-method-complexity-reduce-2 in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.
Refactor a specified method to reduce cognitive complexity to a requested threshold or below by extracting focused helper methods while preserving behavior. Use when the user asks to reduce method complexity, simplify nested conditionals, split large if-else or switch chains, extract validation or type-specific handlers, and verify tests show failed=0. It is listed under Coding & Dev Tools on SkillMD.
This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.
This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.
Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.
paulasilvatech (@paulasilvatech) published this skill. Their other Agent Skills are listed on their SkillMD profile.
paulasilvatech