Skip to content

python-standards content backlog: candidate rules from dogfooding + writing-skills compliance #12

Description

@vircung

python-standards content backlog — the python mirror of #6. Sources: the
2026-07-23 dogfooding and writing-skills review, and the 2026-07-27
review-contract gate dogfooding (three python projects, five runs). None
of these is a defect in 0.2.0 — the plugin produces correct,
contract-conforming reviews; these are coverage and authoring gaps.

P1 — candidate rules (strongest first, by multi-project recurrence)

  • Dead code (modules, functions, dead params/branches) — recurred
    in every audited project; style-no-dead-code / layout-dead-code.
  • Atomic state writes / shared-state thread safety — non-atomic
    writes of resume/recovery state files (critical-level evidence) and
    shared caches mutated under a thread pool; e.g.
    layout-shared-state-thread-safety + an atomic-file-writes rule.
  • cli-subprocess-timeout — with per-path sub-rules: bulk path →
    important, one-shot → minor (one run reported the same class twice
    with split severities and flagged the split itself as the rule
    author's main insight).
  • standard-retry-classification (critical) — all errors treated
    as permanent, no transient-vs-permanent classification before a
    skip-list write.
  • style-exception-fidelity (important) — except Exception masking
    a precise exception; style-metric-correctness (important) — metric
    not measuring what it declares; style-query-safety-guard
    (important) — builder silently returning an unbounded query.
  • layout-destination-collision-safety (critical) — silent overwrite
    of already-ingested data on a name collision;
    layout-identity-key-strength (important).
  • Minors: layout-single-version-source,
    cli-no-source-string-interpolation, cli-retry-diagnostics,
    cli-one-row-per-item, test-no-source-constant-copies,
    test-helpers-not-in-test-modules, style-comments-state-constraints,
    typing-private-helper-clarity, pool-resource return without
    try/finally, duplicate logging of one event, one-state-two-locks.
  • Consider a new python-data-integrity skill — one run proposed
    it for the four critical-level data-integrity gaps (atomic writes,
    retry classification, collision safety, identity keys) instead of
    scattering them across style/layout.

Writing-skills compliance (python part)

  • Description keyword gaps: python-code-style + docstring;
    python-testing + mock/patch; python-typing + Any / type: ignore /
    mypy
    ; python-project-layout + mise.
  • python-plan-review description rewritten to the "Use when…" form.
  • Citation-boilerplate decision (tersen vs centralize) — family-wide,
    decided once with salesforce-standards content backlog: missing rules, deliberate sub-rules, writing-skills compliance #6.
  • Judgment-word predicate → observable predicate: "obvious from one
    screen of context" (python-typing).

Shared family decisions (made once, applied here and in #6)

New rules follow the #8 tag convention and its authoring rubric;
report-contract behavior is owned by the texts shipped in #10.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions