==========
Complexity
==========

Analyze code complexity and rank refactor targets using objective metrics.

Description
-----------

The complexity skill runs language-appropriate complexity tools, ranks
functions by cyclomatic complexity (and maintainability index for Python),
and writes a report under ``resources/agent-docs/reviews/complexity/``.

Supported tools:

- **Python:** ``radon`` (``radon cc``, ``radon mi``)
- **Go:** ``gocyclo`` (default threshold: over 10)

Missing tools are reported with install commands. The skill does **not**
auto-install packages.

Triggers
--------

- ``complexity``
- ``analyze complexity``
- ``find complex code``
- ``refactor targets``
- ``cyclomatic complexity``
- ``code metrics``

Invocation examples:

.. code-block:: text

   /wf:complexity
   /wf:complexity src/
   $complexity
   /complexity path/to/pkg

Workflow
--------

1. **Resolve scope** — user path, else recent ``.py``/``.go`` changes, else
   ask or use the repo root.
2. **Detect languages** — Python and/or Go under the target.
3. **Check tools** — require ``radon`` and/or ``gocyclo``; never silent install.
4. **Run metrics** — capture tool output.
5. **Rank targets** — CC > 10 should refactor; > 20 must; > 30 critical.
6. **Recommend fixes** — open high-CC functions and give specific extract /
   simplify advice.
7. **Write report** — ``resources/agent-docs/reviews/complexity/YYYY-MM-DD-<target>.md``.
8. **Summarise** — overall stats, top 3 targets, report path.

Output
------

- Session summary (counts, top targets)
- Markdown report under ``resources/agent-docs/reviews/complexity/``

Prerequisites
-------------

.. list-table::
   :header-rows: 1
   :widths: 20 30 50

   * - Language
     - Tool
     - Install (user-approved)
   * - Python
     - ``radon``
     - ``pip install radon``
   * - Go
     - ``gocyclo``
     - ``go install github.com/fzipp/gocyclo/cmd/gocyclo@latest``

Relationship to Other Skills
----------------------------

- **thermo-nuclear** — qualitative maintainability / code-judo review
- **review-tests** — test quality only; complexity is primarily production
  metrics

Attribution
-----------

Vendored and adapted from LobeHub skill ``boshu2-agentops-complexity``
(associated with `boshu2/agentops <https://github.com/boshu2/agentops>`_,
Apache-2.0).