code-structure

Code Structure

code-hygiene deletes the liability; this skill shapes the units that remain. Four owners, one test:

• hygiene = DELETE what git or a library already owns -- dead code, a name that lies or says nothing (code-hygiene), a restating comment (comment-hygiene). A rule that says delete X is one of the two hygienes'.
• code-structure = SHAPE THE UNITS -- how the code is decomposed, how units couple, how an interface reads, how a failure reaches a caller, how data carries its own invariants. Everything here assumes the code should exist; the question is what shape its units and boundaries take.
• readable-code = READ -- how a single body reads line by line: control-flow shape, naming across a set, reading order and working set. Anything about how one body reads rather than how the units are carved is readable-code's.
• pythonica = Python mechanics -- a rule that names a Python construct (dataclass, NewType, a context manager, match) is pythonica's; keep this skill language-agnostic.

Read code-hygiene and comment-hygiene first: shaping code that should have been deleted is wasted work. When a fix here would be self-documenting code (a revealing name, an extracted step, an explaining variable), that is exactly what comment-hygiene's "prefer self-documenting code over a comment" meta-rule points to -- that skill removes the comment, this skill supplies the structure. Where a smell reads as "there is redundant knowledge here", check the boundary: identical text in two places is code-hygiene's duplication rule; the same decision in two unlike forms is this skill's (DRY-as-knowledge, below).

Every rule below is a recognizable smell (something a reader or author can actually spot) -> the principle it violates -> a fix direction. No line, parameter, or nesting-depth count gates any rule here: that false precision is the size-fallacy this skill exists to replace. (Illustrative counts like "a two-line loop index" still appear -- they describe an example, they do not set a threshold.)