Skip to content

2026 11 14 refactor round

Dr K edited this page Nov 14, 2026 · 3 revisions

The refactor round: less code, fewer comments, a leaner test suite

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.

What it is for

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.

Rules for every package

  • Work to two skills, read first: skill://superpowers/python-refactor/SKILL.md and skill://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.

Baseline (main at 4603a3a, 2026-11-14)

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.

Packages

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.

Progress

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

Found on the way

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.

Clone this wiki locally