alex-modularize

Files (1)

• SKILL.md

SKILL.md (first lines)

# Alex modularize (plan the structure first)

Structure decided while typing is structure nobody chose. This skill produces a
**file-by-file plan** you approve before any code moves — the recurring ask:

> "yes please. First plan the modules and what you are going to move file by file so that
> we dont miss anything and that prs stay clean"

Sibling skills: `alex-structure` reads the existing map, `alex-api` designs the public
surface. This one decides **where things live** — and on a library change the two are one
decision, so run `alex-api` alongside it.

## Input

- **goal** — what is being built or reorganised
- **constraints** — package boundaries, release order, what must not move yet
- **done_when** — the acceptance statement

## Workflow

### 1. Read the existing structure — never guess it

Query the codebase graph (`alex-structure`) or list the tree. Write down the convention
already in use *before* proposing anything, and name which kind of project it is (step 3)
— the same change lands differently in a published package than in a demo repo.

**Convention is not the same as drift.** `P-style` says match the repo's conventions, and
that holds for anything deliberate: naming, import idioms, how modules are split. It does
not extend to accumulated mess — root clutter, committed outputs, a directory that became
a dumping ground. When the existing layout *is* the problem, say so plainly and propose
the clean target instead of replicating it; that is the one case where this skill
overrides matching what is there.

### 2. Name the responsibilities

List every distinct job the change involves, in one line each. This is the Single
Responsibility pass and it is done in prose, before files exist. Two jobs that always
change together are one responsibility; one job that two callers need for different
reasons is two.

### 3. Place each responsibility — layout depends on the kind of project

There is no single tree. Identify which of these the repo is (look at what already exists;
do not impose the wrong one), then place responsibilities inside that shape.

**Published library** — `trackers`, `re-ID`. Someone installs it and imports it, so the
public surface and the boundary between concerns are the point.

```text
src/<package>/
  <concern>/            # core, cli, eval, io, datasets, annotators, utils…
    __init__.py         # the public exports of this concern
    base.py             # the abstraction, when there is more than one implementation
    <thing>.py          # one file per concrete implementation
    _helpers.py         # private to the concern, underscore-prefixed
tests/<concern>/        # mirrors the package tree
```

**Research repo** — `internal-signals-context-compression`. The load-bearing split is
**reusable method vs one-off exploration**, and mixing them is a review failure:

```text
src/                    # the method: what a result depends on, and what tests cover
experiments/            # one directory per experiment; scripts, configs, findings
knowledge-base/         # literature notes, decisions
tests/ · docs/ · scripts/
```

> A PR that "bundles a library change with three exploratory experiment suites" is two
> changes wearing one hat — the suites are the lab notebook that chose the variant,
> evidence rather than product.

**Applied / demo project** — a pipeline someone runs, not a package someone imports.
Top-level directories are **stages or deliverables**, not layers:

```text
common/                 # shared across stages
<stage>/                # player_stats, pass_alternatives, simulator, training, evaluation…
  run.py · render.py    # the entry points someone actually calls
scripts/ · docs/ · tests/
```

This is the shape that fits, **not a repo to copy**. The applied repos here
(`world_cup_projects`, `tpf_project`) drifted, and their drift is the useful part — these
are the failure modes to plan against, measured:

- **Docs and notes pile up at the root.** `tpf_project` has 34 loose root files
  (`FINDINGS.md`, `GCP_LAUNCH.md`, `DESIGN_DECISIONS.md`, `INSTRUCCIONES_GCP.md`…). Notes
  belong in `docs/`; the root holds README, LICENSE, config and nothing else.
- **Outputs get committed.** `tpf_project` versions 434 files under `data/` and results
  directories. Generated artifacts belong in `.gitignore` with the command that rebuilds
  them written down — a repo that carries its outputs cannot tell you which code produced
  them.
- **Tests never start.** `tpf_project` has none. An applied project still needs the few
  tests that pin the pipeline's contract, even if it will never be published.

**In a published library, validate the placement against the call site before moving on.**
Structure and public surface are not separate decisions: a split that is clean internally
but makes the user import three things to do one job is a *structural* failure, not an API
polish task. Write the lines a user would type against the proposed tree —

```python
from reid import ReIDDataset          # one import for one job?
ds = ReIDDataset("crops/train")       # do they need to know the internal layout?
ds.for_retrieval(...) ; ds.for_training(...)
```

— and if the answer is that they must assemble internals, move the boundary, not the
documentation.

> "i think for the user it would be more useful to load the dataset in just one class and
> have the option to train from it or just evaluate"

> "show me how it would be fully used for training and for evaluating, because it would be
> cool to just pass 1 set of things"

This check is *whether the structure survives contact with a caller*. Designing that
surface — naming, one-object-for-related-workflows, the accessors it exposes — is
`alex-api`; run it alongside this skill on any library change.

From AlexBodner/alexs-rig, MIT.

More from AlexBodner/alexs-rig