Repository navigation
2026 11 14 refactor round
History. Planned 2026-11-14, after the docs round. Nothing has shipped. The work is parent issue #147 with a sub-issue per package below, each built by the agent flow when Dr K starts it. The Progress table is the state of the round.
The code and its tests end smaller than they started, and every feature is exactly as it was. The spec in specs/ says what "as it was" means: a refactor that makes a requirement there untrue has changed behaviour.
- Work to two skills, read first:
skill://superpowers/python-refactor/SKILL.mdandskill://superpowers/natural-writing/SKILL.md. - One kind of change per commit, and the unit suite green after each.
- A behaviour change, however small or however much better, is a stop: note it in the pull request and leave the code alone. A bug found on the way is reported, not fixed.
- Tool docstrings are the descriptions a model reads and the source of the generated wiki pages. They are behaviour. Leave them alone.
- A comments commit passes
ast_same.py(it ships with the refactoring skill). - A code commit leaves the tests unchanged except for imports. A test commit leaves the code unchanged.
- Coverage never drops below the baseline, for the package and for each module touched.
-
tests/golden/and the OpenAPI document don't change. If one must, that is a stop. - Where selenium-flow and mcp-kb do the same job (configuration, auth, the skills, prompts and agents extensions, request headers, MCP instructions), read mcp-kb's version first and move towards the same names and module boundaries. List each difference kept, and why, in the pull request. The docs round's record lists the known differences under "Differs from mcp-kb".
- The spec names code where a reader needs the boundary: about one requirement in seven mentions a
module, function or class. A package that renames or moves one updates the spec's mention in the
same pull request (
grep -rn "<name>" docs/superpowers/specs). The behaviour a requirement states doesn't change; the name it points at may. - A comments commit drops saga citations (
§F1.n) with the rest of the history. When no code cites one, the last package removes the table of them at the end of the ledger. - Each pull request ends with the numbers: code, comment and docstring lines before and after
(
radon raw), the test count, and coverage.
| What | Now |
|---|---|
Python, kubed/selenium_flow and scripts
|
119 files; 23,934 code, 3,594 comment, 6,299 docstring lines |
| Comment and docstring lines per 100 of code | 41 |
| Complexity (radon) | 82 functions at C, 11 at D, 3 at E |
| Unit tests | 4,579 pass, 31 skipped, 191 s |
| Coverage | 97% of 14,461 statements |
Two things the tools already settled: ruff's UP, SIM, C4, RET and PIE are enforced, and
FURB and PERF find four hits; vulture's candidates are all false positives once tests and
decorator registrations count. The savings are in the comments, the repeated shapes and the tests.
Each is a sub-issue and one pull request. R1 comes first. R2 to R9 can go in any order, one at a time. R10 and R11 follow the code. R12 is last.
| Package | Scope | Code / comment lines | Leads |
|---|---|---|---|
| R1 | The safety net | Regenerate the baseline. Run the unit suite three times, once in random order, and list every test that flips. Fix each at its cause, starting with test_nobody_in_control_answers_at_once and the control-notice test. Apply the four FURB/PERF fixes. Start the Progress table here. |
|
| R2 | core/ |
3,480 / 1,638 |
core/actions.py (1,707 lines) and mcp/tools.py repeat the same argument lists. |
| R3 | flows/ |
2,806 / 1,424 |
flows/api.py and flows/run.py repeat the hook arguments; flows/engine.py repeats "saving validates, edits on disk skip it". |
| R4 |
http/, routes.py, errors.py, faults.py
|
3,100 / 1,521 | The shared answer wrapper the package-restructure design promised was never built: GET /secrets shapes its response by hand. |
| R5 |
workspace/, monitor/, names.py, binding.py
|
3,533 / 1,869 |
workspace/workspaces.py is the largest module (1,860 lines). |
| R6 |
mcp/, spec/, server.py
|
3,972 / 1,203 | Per-tool boilerplate; the skills, prompts and agents extensions against mcp-kb's (26 differences listed). |
| R7 |
capture/, bidi/, recordings/
|
2,892 / 909 |
capture/store.py (1,196 lines). |
| R8 |
live/, site_data/
|
1,616 / 427 | |
| R9 |
config.py, secrets.py, redaction.py, urls.py, main.py, principal.py, scripts/
|
2,532 / 902 | Configuration against mcp-kb's (10 differences listed). |
| R10 | Tests: one set of fakes and fixtures | Repeated setup becomes fixtures, copy-pasted fakes become one, look-alike tests become one parametrised test. | |
| R11 | Tests: what proves nothing | Duplicates and pointless tests go, each with a line naming the test that still holds the behaviour. The bench and flame-graph jobs (bench.yml, integration.yml) either fail a pull request on a real regression or go. |
|
| R12 | mcp-kb parity | Read both repos' shared concerns side by side after R2 to R9. Write the recommendation: extract a shared library, or keep the pattern, with the module list and the cost either way. No code. |
In R2 to R9 the order inside a package is: comments and docstrings first (one commit per
directory, proven by ast_same.py), then the repeated shapes, one abstraction per commit.
| Package | Issue | Pull request | State | Code lines after | Comment lines after |
|---|---|---|---|---|---|
| R1 | #148 | todo | |||
| R2 | #149 | todo | |||
| R3 | #150 | todo | |||
| R4 | #151 | todo | |||
| R5 | #152 | todo | |||
| R6 | #153 | todo | |||
| R7 | #154 | todo | |||
| R8 | #155 | todo | |||
| R9 | #156 | todo | |||
| R10 | #157 | todo | |||
| R11 | #158 | todo | |||
| R12 | #159 | todo |
The docs round checked 756 requirements against the code and set aside what looked like bugs. They are in the docs round's record, under each area's drift. None is fixed by this round: each needs Dr K's read and its own issue.
The action pages are generated from the server's tool schemas, so they describe the version that shipped.
selenium-flow · MIT
Start here
Guides
Lifecycle
Going places
Doing things
Getting things out
Site data
Console and network