python-plan-optimization

The python-plan-optimization skill provides a rigorous, 6-phase read-only analysis workflow designed to evaluate Python code blocks embedded within markdown design documents. It is intended for software engineers, architects, and technical leads who need to ensure that their planning documents remain aligned with industry best practices, such as SOLID, DRY, KISS, and YAGNI, before implementation begins. By processing one or more documents, the agent generates comprehensive reports that pinpoint design principle violations, code smells, and opportunities for adopting modern Python features like type hints and dataclasses.

• Multi-phase analysis pipeline: Conducts systematic discovery, assessment, and verification across 6 distinct stages.
• Context-aware thresholding: Adjusts sensitivity based on project maturity levels, including POC, MVP, Private, Enterprise, and Open Source profiles.
• Strict read-only enforcement: Operates without modifying source files, ensuring document integrity while providing actionable, non-intrusive feedback.
• Architectural compliance checking: Validates proposed code against explicit project decisions, chosen tooling, and stated architectural rationale.
• Empirical verification: Requires WebSearch for third-party API claims and validates logic through surrounding context checks, reducing false positives.

Usage notes and practical constraints include:

• Ensure that project type context is provided (e.g., via a preceding determination skill) to configure the appropriate severity and depth of the report.
• The tool requires precise code quoting for all findings; it will fail if it cannot verify code logic within the provided context or if the reference is insufficient.
• It intentionally ignores # TODO or stub implementations, focusing instead on structural and pattern-based analysis.
• The output is structured as a professional analysis report rather than code modification; it is meant to serve as a consultative layer during the design phase.
• Developers should note that for Open Source modes, the agent mandates additional checks for public API documentation and type annotation coverage.
• The agent acts as an analytical safeguard, preventing the recommendation of unreleased Python features or stale data-caching patterns that could introduce architectural debt.