Skip to content

BUZZARDGTA/Session-Sniffer / .agents/skills/refactor

refactor

Verified

Refactor Session Sniffer code to improve structure, readability, duplication, and maintainability while preserving existing behavior. Use when the user invokes /refactor or explicitly requests code restructuring without a behavior change.

Session Sniffer Refactor

Use this skill when the user wants to refactor Session Sniffer.

The goal is to improve code structure and maintainability without changing externally observable behavior. Prefer small, justified changes that fit the existing architecture over broad rewrites.

Refactor Procedure

  1. Inspect the Git working tree and current diff before making changes. Preserve all unrelated user changes.
  2. Identify the user's target and desired outcome. If no target is specified, inspect the reported area or identify a small, high-value refactor supported by concrete evidence; do not refactor the entire repository opportunistically.
  3. Read the relevant implementation, callers, validation configuration, and applicable .agents/rules/*.md guidance before editing.
  4. Trace data flow, state ownership, lifecycle, error handling, and side effects for the code being changed.
  5. Identify a specific structural problem, such as:
    • duplicated logic with identical semantics;
    • a function or class combining separable responsibilities;
    • complex control flow that can be made clearer;
    • unclear naming or unnecessary indirection in the targeted code;
    • repeated conversion or setup logic that belongs in an existing abstraction.
  6. Explain the intended structural change briefly when it is substantial; then make the smallest coherent refactor.
  7. Prefer existing project abstractions and conventions. Do not introduce a new manager, service layer, registry, wrapper, base class, or helper module unless the code demonstrates a real need.
  8. Update all affected call sites together following the No Backward Compatibility rules in .agents/rules/core.md (do not leave compatibility aliases, shims, or duplicate implementations).
  9. Review the complete diff for accidental behavior changes, unrelated edits, and formatting churn.
  10. Run the smallest relevant configured validation, then broaden it when the risk warrants it.
  11. Report the structural problem, the refactor, files changed, checks actually run, and any remaining risk.

Behavior-Preservation Requirements

Unless the user explicitly asks for a behavior change, preserve:

  • public and internal behavior, return values, side effects, and error semantics;
  • execution order where order can affect results;
  • initialization and shutdown behavior;
  • ownership and lifetime of state;
  • signal/slot wiring and Qt thread boundaries;
  • configuration loading, settings persistence, and data formats;
  • logging meaning and severity;
  • network and packet-processing behavior;
  • resource cleanup and exception propagation.

Do not treat a refactor as permission to redesign APIs, change defaults, remove features, or modernize unrelated code. Do not combine performance optimization, bug fixes, dependency upgrades, or cosmetic cleanup with a structural refactor unless it is essential to the requested change; separate independent work.

Architecture and Performance

  • Follow the existing architecture documented in .agents/rules/architecture.md and applicable subsystem rules.
  • Trace callers and consumers before moving code or changing ownership.
  • Preserve threading, queue, synchronization, and worker-lifecycle patterns.
  • Do not add allocations, repeated parsing, extra work in hot paths, or new blocking operations without a demonstrated reason.
  • Do not change polling intervals, timers, retry behavior, or event frequency as part of a behavior-preserving refactor.
  • Follow the file sizing rules in .agents/rules/python.md ("File Sizing and Structural Warnings"): leave cohesive data tables, schemas, and defaults registries intact; do not split files solely to satisfy line-count metrics.

Code Quality

  • Follow the project's authoritative pyproject.toml and .agents/rules/ instructions.
  • Reuse existing types, utilities, and error-handling patterns.
  • Keep names precise and intent-revealing.

Validation

Follow the validation workflow and configured tooling in .agents/rules/testing.md.

  • Start narrowly with targeted linter and type-checker runs against the touched paths.
  • Broaden validation to the full suite (python code_quality_checks.py) when the risk warrants it.

Scope and Safety

Follow the Git, Change Discipline, Line Endings, and Verification rules in .agents/rules/core.md.

  • Do not modify files merely to make validation pass.

Final Report

Summarize:

  • Structural issue: what made the original code harder to maintain.
  • Refactor: what moved, was extracted, simplified, or deduplicated.
  • Behavior: why the observable behavior should remain unchanged, including any assumptions.
  • Files: files changed.
  • Validation: exact checks run and their results.
  • Remaining risks: anything that could not be verified.
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 318kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 318kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 318kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 318kUpdated Claude CodeCodexVerifiedInstall