quality-screener-mcp-server: Skill for Claude Code

Backend Code Simplifier

Expert simplification of Python backend code. Make the code easier to read, safer to evolve, and more consistent with project standards — without changing observable behavior.

Core Goal

Preserve functionality exactly while reducing accidental complexity.

Prefer explicit, boring, maintainable Python over clever or overly compact code. A few extra lines that read top-to-bottom are almost always better than a dense expression that requires a debugger to understand.

Mental Model — "Make It Boring"

When in doubt, ask:

1. Can a new reader summarize this function in one sentence? If not, split it.
2. Does the happy path read top-to-bottom without diving into branches? If not, hoist guard clauses and flatten nesting.
3. Is every name a noun for data, a verb for action? If not, rename.
4. Does the abstraction earn its keep at this call site count? If only one caller uses it, inline it. If three+ callers use a near-duplicate, extract it.
5. Could you delete this code and still pass the tests? If yes, delete it.

Project Standards (Non-negotiable)

• Keep full type annotations on functions; do not drop them to "simplify".
• Keep Google-style docstrings where the codebase has them.
• Respect existing service-layer and module boundaries (api/, analysis/, financial/, database/).
• Reuse existing helpers and patterns before introducing new abstractions.
• Reuse research/ prototypes when the simplification target maps to one.
• Keep changes pytest-friendly; do not break fixtures or test seams.
• Do not run ruff or type checking unless the user explicitly asks.

Simplification Priorities (In Order)

1. Preserve Behavior — Always

Do not change API contracts, database semantics, scheduling cadence, auth behavior, numerical/financial logic, or response shapes unless the user asks for a behavioral change. When uncertain, ask before editing.

2. Reduce Complexity

• Flatten deeply nested conditionals; prefer guard clauses and return early.
• Replace "do everything" functions with smaller helpers — but only when the split is natural (one clear noun/verb each), not just to lower line counts.
• Remove duplicated logic; consolidate near-duplicate branches.
• Eliminate one-use abstractions, pass-through wrappers, and needless indirection.
• Replace boolean-flag pyramids with explicit control flow or enum dispatch.
• Break apart dense comprehensions / chained expressions when readability suffers.
• Prefer table-driven dispatch (dict / match) over long if/elif ladders.