plan-lower-code-complexity_skill

Overview

This skill reduces the repository's cognitive complexity threshold by 2 and produces a concrete remediation plan to fix all resulting violations. It identifies every function that exceeds the new limit, prepares a structured brief with refactoring strategies, and generates a taskized plan suitable for delegated execution. The output is ready to feed into an execution agent or project board.

How this skill works

The skill reads the current cognitive-complexity value from the ESLint config, calculates newThreshold = current - 2, and runs the linter with that limit to discover violations. For each violation it records file path, line number, function name, and complexity score, then compiles a brief that lists offending functions ordered by complexity and outlines refactoring strategies. Finally it produces a step-by-step plan of tasks to fix each violation and verification steps to confirm zero remaining errors.

When to use it

• When the codebase needs stricter maintainability rules and lower cognitive complexity.
• Before a cleanup sprint targeting hard-to-maintain functions or high-complexity modules.
• When preparing a codebase for larger refactors or onboarding new maintainers.
• When automated governance requires progressively stricter linting thresholds.
• If the current threshold is permissive and you want incremental tightening.

Best practices

• Run the linter locally with the new threshold to validate results before changing config.
• Order fixes by impact: high-complexity, high-usage functions first.
• Use small, reviewable commits that encapsulate a single refactoring strategy.
• Prefer automated tests and linters to detect regressions after each change.
• Document why complexity was reduced for future maintainers.

Example use cases

• Lowering cognitive complexity from 15 to 13 across a TypeScript service repository and generating a refactor plan.
• Preparing a prioritized task list for developers to address all functions exceeding the new threshold.
• Creating a brief for an automated execution agent to implement small refactors and verify lint pass.
• Enforcing incremental policy changes in a governance framework where thresholds are tightened over time.