What is the 'Complexity Formula' mentioned in the skill?

Complexity (C) equals the sum of each part's complexity weighted by the time developers spend working with that part. Complexity in rarely touched code is less critical than in high-traffic modules.

How does this differ from standard linting or 'red-flags' skills?

While linting looks for syntax or style and 'red-flags' look for specific smells, this skill is a diagnostic lens to identify the structural source of friction in a system.

What are the three symptoms of complexity it identifies?

The skill looks for Change Amplification (modifying many files for one change), Cognitive Load (high mental effort to understand), and Unknown Unknowns (invisible requirements).

What is the core philosophy behind the Complexity Recognition skill?

It is based on John Ousterhout's 'A Philosophy of Software Design,' which defines complexity as anything that makes a system hard to understand or modify.

When should I invoke this skill in Claude Code?

Use it when you feel code is harder to work with than it should be, or during 'should we refactor?' discussions to provide objective reasoning for design changes.

Software Complexity Diagnostic

Name: Software Complexity Diagnostic
Author: codybrom

bycodybrom

•

Collaboration Tools

Diagnoses the root causes of software complexity using the three-symptom, two-root-cause framework from A Philosophy of Software Design.

The Complexity Recognition skill acts as a high-level architectural review lens for Claude, grounded in the principles of John Ousterhout's software design philosophy. It helps developers move beyond 'gut feelings' about bad code by identifying measurable symptoms like change amplification and cognitive load. By tracing these issues back to their root causes—dependencies and obscurity—this skill provides actionable insights into whether complexity should be eliminated through redesign or encapsulated within deep modules. It is especially effective for evaluating 'hot paths' where complexity impacts development velocity the most.

Key Features

01Identifies Change Amplification: Tracks if single conceptual changes require edits in many places.

023 GitHub stars

03Exposes Unknown Unknowns: Surfaces hidden dependencies and undocumented constraints that lead to bugs.

04Strategic Refactoring Guidance: Determines whether to eliminate complexity or encapsulate it in deep modules.

05Weighted Complexity Analysis: Prioritizes issues in high-traffic code paths using the complexity formula.

06Assesses Cognitive Load: Evaluates how much specialized knowledge a developer needs to modify a module safely.

Use Cases

01Conducting architectural reviews when a codebase begins to feel 'heavy' or slow to modify.

02Evaluating potential refactors to ensure they actually reduce cognitive load rather than just making code terser.

03Prioritizing technical debt by identifying which complex modules are modified most frequently.

What are Skills?·How to Install

Install with 🐟 Skill.Fish

npx skillfish add codybrom/clairvoyance complexity-recognition

For use in Claude.ai and ChatGPT

Key Features

01Identifies Change Amplification: Tracks if single conceptual changes require edits in many places.

023 GitHub stars

03Exposes Unknown Unknowns: Surfaces hidden dependencies and undocumented constraints that lead to bugs.

04Strategic Refactoring Guidance: Determines whether to eliminate complexity or encapsulate it in deep modules.

05Weighted Complexity Analysis: Prioritizes issues in high-traffic code paths using the complexity formula.

06Assesses Cognitive Load: Evaluates how much specialized knowledge a developer needs to modify a module safely.

Use Cases

01Conducting architectural reviews when a codebase begins to feel 'heavy' or slow to modify.

02Evaluating potential refactors to ensure they actually reduce cognitive load rather than just making code terser.

03Prioritizing technical debt by identifying which complex modules are modified most frequently.