home / skills / codyswanngt / lisa / plan-lower-code-complexity

plan-lower-code-complexity skill

safe

/.claude/skills/plan-lower-code-complexity

This skill reduces cognitive complexity threshold by two, identifies violations, and creates a practical plan to refactor code now.

npx playbooks add skill codyswanngt/lisa --skill plan-lower-code-complexity

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

1.5 KB

---
name: plan-lower-code-complexity
description: This skill should be used when reducing the cognitive complexity threshold of the codebase. It lowers the threshold by 2, identifies functions that exceed the new limit, generates a brief with refactoring strategies, and creates a plan with tasks to fix all violations.
allowed-tools: ["Read", "Bash", "Glob", "Grep"]
---

# Lower Code Complexity

Reduces the cognitive complexity threshold by 2 and fixes all violations.

## Step 1: Gather Requirements

1. **Read current threshold** from eslint config (cognitive-complexity rule)
2. **Calculate new threshold**: current - 2 (e.g., 15 -> 13)
3. **Run lint** with the new threshold to find violations:
   ```bash
   bun run lint 2>&1 | grep "cognitive-complexity"
   ```
4. **Note for each violation**:
   - File path and line number
   - Function name
   - Current complexity score

If no violations at new threshold, report success and exit.

## Step 2: Compile Brief and Delegate

Compile the gathered information into a structured brief:

```
Reduce cognitive complexity threshold from [current] to [new].

Functions exceeding threshold (ordered by complexity):
1. [file:function] (complexity: X, target: [new]) - Line Y
2. ...

Configuration change: [eslint config path], cognitive-complexity from [current] to [new]

Refactoring strategies: extract functions, early returns, extract conditions, use lookup tables

Verification: `bun run lint 2>&1 | grep "cognitive-complexity" | wc -l` → Expected: 0
```

Invoke `/plan-execute` with this brief to create the implementation plan.

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.

FAQ

What happens if no functions exceed the new threshold?

The skill reports success, shows the checked threshold and zero violations, and does not create further remediation tasks.

Which refactoring strategies are recommended?

Extract helper functions, apply early returns, simplify conditional logic (extract conditions), and replace complex branches with lookup tables where appropriate.