explore-dependencies

name	explore-dependencies
description	Explores installed ataraxis dependency source code to build a live API snapshot of the public classes, functions, and constants/enums each dependency exports, flagging where project code reimplements existing library functionality. Use when starting a session on a project with ataraxis dependencies, before writing code that uses ataraxis library features, or when the user asks about available library APIs.
user-invocable	true

Dependency exploration

Explores installed ataraxis dependency source code to build a live API snapshot for the current project.

You MUST run this skill before writing code that uses ataraxis library features. Static reference tables go stale, and reading the actual installed source is the only reliable way to know what APIs are available and how they work.

---

Scope

Covers:

• Discovering ataraxis dependencies from pyproject.toml
• Locating installed package source code on disk
• Reading __init__.py and __all__ exports to enumerate public API surfaces
• Reading source signatures, docstrings, and return types for each public asset
• Cross-referencing project code against discovered APIs to find replacement opportunities
• Producing a structured "Dependency API snapshot" organized by library

Does not cover:

• Third-party library exploration (NumPy, Click, etc.), for which you read the docs directly
• Modifying dependency versions or adding new dependencies (see /pyproject-style)
• Applying Python coding conventions (see /python-style)
• Exploring the project's own codebase structure (see /explore-codebase)

---

Workflow

You MUST follow these steps when this skill is invoked.

Step 1: Load the library catalog

Read library-catalog.md to understand the ataraxis library ecosystem, domain-to-library mappings, and import names.

Step 2: Identify project dependencies

Read the project's pyproject.toml and extract all ataraxis dependencies from the dependencies array in [project], [project.optional-dependencies], and [dependency-groups] (PEP 735). Ataraxis projects place dev dependencies such as ataraxis-automation in [dependency-groups], not under [project.optional-dependencies] (see /pyproject-style). Match package names that start with ataraxis-, that start with the project's own first-party namespace prefix, or that the catalog names outright, which is how cindra is reached.

If pyproject.toml is not found, check for setup.cfg, setup.py, or requirements.txt as fallbacks.

Record each dependency with its package name and corresponding import name (replace hyphens with underscores).

Step 3: Locate installed source code

For each identified dependency, resolve the installed package location:

python -c "import <import_name>; print(<import_name>.__file__)"

This returns the path to the package's __init__.py. The parent directory contains all source modules.

Obtain the package version with the hyphenated PyPI name, not the import name. Ataraxis __init__.py files do not expose __version__, so resolve it at runtime instead:

python -c "import importlib.metadata; print(importlib.metadata.version('<package-name>'))"

Reconcile local or editable checkouts. When a dependency's resolved __file__ falls outside site-packages (e.g. it points to a sibling or parent directory), it is a local or editable checkout that may be ahead of or behind the published release. Look up the dependency's GitHub repository from library-catalog.md. Do NOT hardcode the Sun-Lab-NBB org, because first-party application libraries may live under a different owner. Skip any dependency with no cataloged repository. For every remaining dependency, compare the local version against the latest release:

gh api repos/<owner>/<repo>/releases/latest --jq .tag_name

Flag any drift between the local checkout and the latest release before treating the local API as authoritative.

For C++ ataraxis libraries (ataraxis-transport-layer-mc, ataraxis-micro-controller), the python -c "import ..." resolution does not apply. Locate the source under .pio/libdeps/<env>/<lib>/src, where <env> is the PlatformIO environment name from platformio.ini. Read the library version from the version field of the library's library.json (not importlib.metadata). Enumerate public classes from the library's header files rather than from __all__ (see Step 4).

If a package is not installed, note it as unavailable and skip to the next dependency.

Step 4: Enumerate public APIs

For each installed Python dependency:

1. Read the package's __init__.py file
2. Extract the __all__ list to identify all public exports
3. For each exported name, identify whether it is a class, function, constant, or enum
4. Group exports by category (classes, functions, constants/enums)

For C++ dependencies there is no __init__.py or __all__. Instead, read the public header files under .pio/libdeps/<env>/<lib>/src and enumerate the public classes, structs, and enums they declare, grouping them the same way.

Step 5: Read API details

For each public class and function discovered in Step 4:

1. Locate the source module that defines it (follow the import in __init__.py)
2. Read the definition to extract:
   • Signature: Full function/method signature with type annotations
   • Docstring summary: First line of the docstring
   • Key parameters: Parameter names, types, and defaults
   • Return type: The annotated return type
3. For classes, also extract:
   • __init__ signature: Constructor parameters
   • Public methods: Method names and their signatures
   • Class/static methods: Any @classmethod or @staticmethod methods

Focus on signatures and summaries. Do not read full method bodies unless needed to understand behavior.

Step 6: Identify replacement opportunities

Scan the project's source code for patterns that duplicate functionality provided by the discovered dependency APIs:

Pattern in project code	Likely replacement
print() or click.echo() for output	console.echo() (with raw=True if needed)
raise for error reporting	console.error()
isinstance chains to normalize to list	ensure_list()
Manual slicing loops for batching	chunk_iterable()
os.cpu_count() arithmetic	resolve_worker_count()
time.sleep() or time.time() patterns	PrecisionTimer methods
datetime.now().strftime() calls	get_timestamp()
Manual yaml.dump()/yaml.load() calls	YamlConfig subclass
multiprocessing.Array or Value usage	SharedMemoryArray
Direct file writes in acquisition loops	DataLogger + LogPackage
os.makedirs() or Path.mkdir() patterns	ensure_directory_exists()

Report each replacement opportunity with the file location and the suggested library alternative.

Treat the table above as starter heuristics, not an authoritative catalog. Before recommending any replacement, confirm the named symbol appears in the __all__ exports enumerated in Step 4 (and in the signature read in Step 5). Never suggest a symbol absent from the live snapshot. Delete a replacement row whose symbol is missing from this run's per-library tables rather than repairing it.

Step 7: Produce the dependency API snapshot

Present the results using the output format below. This snapshot gives the agent (and user) a complete picture of what the project's ataraxis dependencies provide.

---

Output format

Organize the snapshot by library, with sections for each dependency.

Per-library section

## <library-name> (v<version>)

**Import:** `from <import_name> import ...`
**Source:** `<installed_path>`

### Classes

| Class       | Summary           | Key methods                    |
|-------------|-------------------|--------------------------------|
| `ClassName` | Docstring summary | `method_one()`, `method_two()` |

### Functions

| Function        | Signature                           | Summary           |
|-----------------|-------------------------------------|-------------------|
| `function_name` | `(param: type, ...) -> return_type` | Docstring summary |

### Constants and enums

| Name            | Type   | Summary                              |
|-----------------|--------|--------------------------------------|
| `CONSTANT_NAME` | `type` | Description                          |
| `EnumName`      | `enum` | Members: `MEMBER_A`, `MEMBER_B`, ... |

For C++ libraries, replace the **Import:** line with an **Include:** line naming the header (e.g. #include "transport_layer.h") and set **Source:** to the .pio/libdeps/<env>/<lib>/src location, so a project building for several boards carries one tree per environment.

Replacement opportunities section

After all per-library sections, include a summary of replacement opportunities:

## Replacement opportunities

| File               | Current pattern   | Suggested replacement                   |
|--------------------|-------------------|-----------------------------------------|
| `src/module.py:42` | `print(table)`    | `console.echo(message=table, raw=True)` |
| `src/utils.py:15`  | `time.sleep(0.1)` | `PrecisionTimer.delay()`                |

If no replacement opportunities are found, state: "No replacement opportunities identified."

---

Handling large dependencies

For a dependency with 15 or more public exports, or when the public exports across all dependencies total 30 or more, use the Agent tool with the Explore agent type to parallelize the API reading. Launch at most 2-3 Explore sub-agents, batching libraries across them rather than one sub-agent per library. Instruct each sub-agent to return ONLY the structured snapshot rows for its assigned libraries (signatures plus one-line summaries), never raw source bodies.

When every dependency has fewer than 15 public exports and they total fewer than 30 across all dependencies, read the APIs directly without sub-agents.

---

Related skills

Skill	Relationship
/python-style	Requires this skill before writing code that uses ataraxis features
/cpp-style	Provides C++ conventions for ataraxis libraries explored here
/pyproject-style	Manages dependency versions and additions. Defer dependency changes to it
/explore-codebase	Explores project structure. Invoke alongside this skill at session start
/commit	Invoke after completing code changes informed by the API snapshot

---

Proactive behavior

Invoke at session start alongside /explore-codebase when the project has ataraxis dependencies. The /python-style skill explicitly requires this skill before writing code that touches ataraxis library domains.

When invoked proactively, present the dependency API snapshot and replacement opportunities before proceeding to code changes. Wait for user acknowledgment before modifying code.

---

Verification checklist

You MUST verify the exploration output against this checklist before presenting it to the user.

Dependency Exploration Compliance:

Judgment items. No tool inspects the exploration output, so this checklist is its only enforcement.
Walk every one against the summary you are about to present.
- [ ] All ataraxis dependencies identified (incl. [dependency-groups], not just [project] dependencies)
- [ ] Unavailable packages noted and skipped
- [ ] __all__ exports read for each installed Python dependency
- [ ] C++ (.pio/libdeps) dependencies enumerated from header files where applicable
- [ ] Reading depth matched the export count: direct read under 15 exports, otherwise at most 3 Explore
      sub-agents batching libraries and returning snapshot rows only
- [ ] Public classes documented with constructors and public methods
- [ ] Public functions documented with signatures and summaries
- [ ] Constants and enums documented with types and members
- [ ] Replacement opportunities reported with file:line location and concrete suggested replacement
- [ ] Every suggested replacement names a symbol present in this run's enumerated __all__ exports, with its
      signature read, and no symbol carried over from the starter heuristics table unconfirmed
- [ ] Empty replacement scan stated as "No replacement opportunities identified." rather than an omitted section
- [ ] Output organized by library with consistent table format
- [ ] C++ sections use an Include line naming the header and a .pio/libdeps source path, not an Import line
- [ ] Snapshot includes version numbers where available
- [ ] No code modifications made during exploration

Tool-settled items. Run `python -c "import <import_name>; print(<import_name>.__file__)"` and
`gh api repos/<owner>/<repo>/releases/latest --jq .tag_name` to settle these rather than recalling
them. They stay listed for reviews performed without a shell.
- [ ] Each installed dependency's source location resolved
- [ ] Local/editable checkouts reconciled against latest GitHub release where a repo is cataloged