vesey.techvvcleanup.md

Let's now do some cleanup:

  1. Code
  • While you were working, did you encounter any code or patterns that made your job harder than it should be?
  • Anything that needs renaming, reorganizing, deduplicating, or refactoring?
  • Anything that is becoming too long, too complex, or spaghettified?
  • Anything that is hacky or not best-practices?
  • Anything that is currently hardcoded but probably shouldn't be?
  • Any dead or leftover code?
  • Any unnecessary reinvention of the wheel?
  • Any unhandled build warnings?
  • Anything else generally that you feel deserves a callout? Don't worry about effort or complexity - after all, being an LLM, time and 'effort' are not concepts for you, only possibility and correctness. If on the other hand everything is looking pretty good, don't feel like you need to invent problems to fix.

Provide identified code issues as a numbered list

  1. Non-code

Ensure that any and all of the non-code content you incidentally read, directly wrote, or otherwise touched during this session adheres to the following:

  • Code comments should ONLY be used where code is not reasonably self-documenting, or where a function's body is complex enough to warrant a terse explanation of its behavior so its entire body does not need to be read out. Same with whole-file docstrings.
  • Reduce the number of duplicates of functional truth for a piece of logic. For example: a function's code, its code comments, its function docstring, its module/file docstring, and separate doc file(s) mentioning its behavior are separate sources of truth that can and will drift from each other. Deduplicate these aggressively.
  • Tersen docs where at all reasonable, and remove comments and docs entirely that are not useful. Don't be afraid to prune aggressively to eliminate unnecessary verbosity.
  • Prefer language brevity and simplify linguistic complexity
  • Docs should describe at most a high-level map of the landscape of logic, not descend into becoming the landscape themselves
  • Docs should additionally describe the current view of logic and systems, and unless extremely well motivated should exclude historical details, as most of these will be irrelevant and self-evident by reading a git diff or commit message.
  • Where historical details are necessary, avoid specifics and historical framing that are irrelevant ("foo() previously called bar(), but that didn't work due to..." vs "avoid calling bar(), because...")
  • Docs should describe the subject, not the task or process that produced them, ("we added", "now archived", "as discussed")
  • Docs should exclude relative-time and novelty framing ("currently", "recently", "the new X", "as opposed to the previous system...")
  • Anchor any time-sensitive claims to absolute dates rather than relative ones
  • Avoid invented jargon where possible, some notable examples including "the ratchet", "the spine", "the split". This is unselfevident and works against the principle of quick grokking through skimming.
  • Ensure the docs are generally up to date to reflect any changes you may have made (keeping in mind the above principles) Think critically about the files, docs, comments, and other non-functional ancillary text you've read thus far and think about what changes are necessary so everything strives to meet these principles.

You do not need to include docs or non-code issues in the numbered list, that is just for code issues. Feel free to address inert non-code issues without explicit approval.

Wait for the user to confirm which non-inert functional numbered items they want addressed before proceeding.