python-refactoring

Refactor the marked code (or the current file if nothing is marked) following these project rules:

Structure & Style

1. No wrapper functions for simple reads: Access config values directly. Do NOT create helper functions like get_team_name() just to return config.TEAM. Use config.TEAM directly where needed.

2. No premature abstractions: Don't extract functions just to reduce line count. Three similar lines is better than a helper called only once. Do extract functions when they serve a structural purpose — avoiding nested try/except, giving a name to a distinct logical step, or keeping a function flat.

3. No separate variables for one-time values: If a value is only used once and is simple (a config read, a constant), inline it. Don't create team_name = config.TEAM three lines before its only use — just use config.TEAM directly. Exception: don't nest function calls like extract_result(await run_query(...)). When one function's output feeds into another, use an intermediate variable so each step is debuggable on its own line.

4. Imports: Prefer imports at the top of the file. Remove unused imports. Use from autosprint.config import config for config access. Lazy imports inside functions are acceptable when there's a good reason — optional dependencies that may not be installed, or circular imports. In those cases, add a comment explaining why. Use judgment: if the dependency is always available, move it to the top.

5. Type hints: Add type hints to all function parameters, return types, and variables where the type isn't obvious from the assignment. Treat Python like TypeScript — everything should be typed. Use from __future__ import annotations at the top of each file for modern syntax.

6. Every function gets a one-line docstring placed immediately after the def line and before the try keyword. Exactly one line — no multi-line docstrings, no parameter tables, no type repetition. Describe the what, not the how.

   Phrasing by function kind (Command-Query Separation):

   • Query (primary purpose is to return a value): start the docstring with Returns <what it returns>. Example: """Returns the current HEAD commit hash as a short string."""
   • Command (primary purpose is a side effect — writes a file, calls an API, mutates state): start with an imperative verb describing the action. Example: """Append a sprint outcome line to ai-run.log."""
   • Mixed (both returns something meaningful AND has a non-trivial side effect, e.g. mutates state or writes to disk): describe both briefly — action first, then what's returned. Example: """Run the Plan phase, write plan.md, and return (plan, next_task, sprints_since_replan).""" Prefer splitting such functions when practical.

   Observability logging in queries is fine. A Query may call printlev to log its decision, a cache hit/miss, or why it returned what it did. This is not a "Mixed" function — stdout/log output is observability, not state mutation. Treat the function as a Query for phrasing purposes (Returns ...), and optionally mention the log in the docstring if it's load-bearing. Example: """Returns (True, reason) if plan.md should be regenerated and prints the reason; else (False, "").""" The CQS rule about "queries should not have side effects" is aimed at mutations (writing files, changing DB state, mutating arguments) — not at tracing what the function decided.

   On every refactor, verify the docstring is still an accurate summary of what the function does — if the function's behaviour drifted, rewrite the line; a stale one-liner is worse than none. Don't add other inline comments unless the logic isn't self-evident.

7. Prefer long lines over line breaks: Max line width is 1000. Do not manually break lines for readability — keep statements on a single line even if they're long. Let black handle formatting.

8. Bottom-up function ordering: Entry points (main, if __name__) at the bottom. Leaf/utility functions near the top. Constants and module-level definitions at the very top after imports.