Python Plan Optimization

Analysis Workflow

Analyzes code blocks in design documents to identify improvement opportunities using established design principles, modern Python practices, and systematic code smell detection.

Core Mission

Analyze Python code in planning documents to identify improvement opportunities by:

1. Detecting design principle violations (SOLID, DRY, KISS, YAGNI)
2. Identifying code smells and anti-patterns
3. Suggesting modern Python alternatives (type hints, dataclasses, etc.)
4. Respecting explicit architectural decisions and chosen tooling
5. Presenting findings as opportunities, not requirements

Deliverable: Analysis report with recommendations (documents are NOT modified).

Constraints

Read-Only Scope:

• Do NOT modify any files
• Do NOT apply suggested changes automatically
• Present all findings as recommendations for consideration

MUST Respect:

• Explicit architectural decisions stated in the document
• Chosen tooling and library decisions with stated rationale
• Application-level design choices
• External dependencies and integrations as documented
• Intentional placeholders and incomplete sections (# TODO, # ..., stub implementations)

MAY Suggest (as opportunities):

• Internal code organization improvements
• Class hierarchy and composition alternatives
• Method extraction and decomposition patterns
• Modern Python idiom adoption
• Type annotation additions

NEVER (will cause analysis failure):

• Make claims about code without quoting the exact code (minimum 3 lines with line numbers)
• Report issues when a solution already exists in surrounding context (±20 lines)
• Conflate patterns from different code blocks/stages
• Misrepresent line counts—report logic lines separately from total (e.g., "60 lines of logic, 95 total" not "~95 lines")
• Recommend specific library APIs (imports, exceptions, classes, attributes, behavior) without WebSearch verification—package splits are common
• Recommend patterns for time-dependent data (age_days, timestamps) that would cache stale values (including @cached_property, @computed_field, memoization)
• Suggest type wrappers (enums, classes) when SDK already provides Literal[...] types, or over-constrain generics breaking valid use cases
• Cite features from unreleased Python versions

6-Phase Workflow

Phase 0: Project Type Context

Before analyzing documents, determine the analysis configuration based on project type.

Check for Project Type in Context:

1. Look for project_type: in the conversation context (set by project-type-determination skill)
2. If found → use that type for threshold configuration
3. If not found → default to private (most permissive, matches pre-v2.0.0 behavior)

Load Profile from references/project-type-profiles.md:

Store Configuration:

• include_severities: List of severities to report
• include_smell_categories: List of smell categories to check
• require_web_verification: Boolean or "critical_only"
• educational_mode: Boolean (explain "why" for each finding)
• require_type_hints_public: Boolean (opensource only)
• require_docs_public: Boolean (opensource only)

Output for Report Header:

project_type: [type]
project_type_source: [prompt|document|user|default]
analysis_mode: [description from profile]

Phase 1: Discovery

Understand the codebase context and identify explicit decisions.

For each document:

1. Read the document completely
2. Identify all Python code blocks (fenced with ``` or indented)
3. Catalog the purpose of each code example
4. Note dependencies between code examples
5. Identify the Python version targeted (assume 3.10+ unless specified)
6. Identify explicit architectural decisions and tooling choices

Error Handling:

• If a document cannot be read: mark as failed, record reason, continue to next
• If no code blocks found: mark as skipped, record reason, continue to next

Cross-Document Tracking (when multiple documents):

• Note shared patterns across documents
• Track common dependencies
• Flag potential inconsistencies between documents

Discovery Questions:

• What is the purpose of this code?
• What external dependencies exist?
• Are there constraints mentioned in surrounding text?
• How do code blocks relate to each other?
• What explicit decisions have been made and why?
• Are there patterns shared across documents?

Phase 2: Assessment

Evaluate code against design principles and identify issues. Apply project type filters from Phase 0.

Pre-Assessment: Apply Type Filters

Before evaluating findings, apply the project type configuration:

• Severity Filter: Only assess issues at or above the threshold (e.g., POC = Critical only)
• Smell Category Filter: Only check included categories (e.g., MVP = Bloaters only)
• Open Source Checks: If opensource, also check for missing type hints and docs on public API

For EACH potential finding, you MUST:

1. Quote the exact code (minimum 3 lines, include line numbers)
2. Trace data flow to verify the problem causes incorrect behavior (pattern match alone is insufficient)
3. Check ±20 lines for an existing solution
4. Confirm you're analyzing the correct file/stage
5. For third-party library claims: WebSearch the exact API name—only include if documentation confirms it exists (no confirmation = do not claim)

If ANY verification step fails, do NOT include the finding.

Principle Checklist:

Code Smell Categories:

See references/design-principles.md and references/code-smells.md for detailed detection patterns.

Phase 3: Planning

Prioritize findings and organize recommendations. Apply project type severity filters.

Planning Steps:

1. Prioritize issues by impact (Critical > High > Medium > Low)
2. Filter to included severities based on project type (from Phase 0)
3. Group related issues that should be addressed together
4. Filter out suggestions that conflict with explicit architectural decisions
5. Organize recommendations by code block
6. If enterprise/opensource: Mark findings that need web verification

Severity Assessment:

Before assigning severity, ask:

1. Under what deployment conditions does this issue actually manifest?
2. Is this demonstrated in the code flow, or only theoretical?
3. Does fixing this actually improve the code, or just satisfy a pattern?

Phase 4: Recommendations

Generate improvement suggestions with alternatives.

Recommendation Approach:

1. Present one principle/pattern improvement at a time
2. Show before/after code examples (as suggestions, NOT applied)
3. Explain the benefit of each suggested change
4. Note any tradeoffs or considerations
5. Clarify these are opportunities, not requirements

Modern Python Practices:

See references/modern-python.md for detailed guidance.

Phase 5: Report

Generate comprehensive analysis report. Include project type context in header.

Output Format:

## Analysis Report

**Project Type:** [type] (source: [prompt|document|user|default])
**Analysis Mode:** [description from profile]

---

### Summary

| Metric | Count |
|--------|-------|
| Documents Analyzed | [count] |
| Documents Skipped | [count] |
| Total Code Blocks | [count] |
| Total Issues Found | [count] |
| Total Recommendations | [count] |

### Severity Distribution

| Severity | Count |
|----------|-------|
| Critical | [n] |
| High | [n] |
| Medium | [n] |
| Low | [n] |

---

## Document: [path/to/document.md]

**Status:** SUCCESS|PARTIAL|SKIPPED|FAILED
**Code Blocks Analyzed:** [count]
**Issues Found:** [count]
**Architectural Decisions Respected:** [count]

### Architectural Context

[List of explicit decisions recognized in this document]

### Code Block Analysis

#### Block 1: [description]

**File/Stage:** [explicit identifier - e.g., "Stage 2: execute_search"]

**Architectural Context:**
[Decisions that apply to this block - these are respected]

**Finding 1:** [issue title]

**Code (lines X-Y):**
```python
# Exact code being critiqued (minimum 3 lines)

Issue: [What the problem is]

Suggested Improvement:

# Recommended alternative

Rationale: [Why this could help]

[Repeat for additional documents...]

Cross-Document Observations

[If multiple documents: patterns, inconsistencies, shared opportunities]

Important: This is a read-only analysis. No files have been modified.

**Report Guidelines:**
- Present summary first for quick overview
- Generate per-document sections with findings
- Note cross-document patterns when analyzing multiple files
- Use collapsible sections for lengthy findings if needed

## Respecting Architectural Decisions

When the document contains explicit architectural decisions or tooling choices:

**Recognition Patterns:**
- "We chose X because Y"
- "The decision to use X was made due to"
- "Given the constraints, we selected"
- "The architecture uses X for..."
- Explicit technology/library choices with rationale

**Handling:**
1. **Acknowledge** the decision in the analysis
2. **Do NOT suggest** replacing the chosen approach
3. **MAY suggest** improvements within the chosen framework
4. **Clarify** that suggestions are opportunities, not requirements

**Example:**
If document says "We use SQLAlchemy for ORM because of existing team expertise":
- ✅ Suggest: "Consider using SQLAlchemy's hybrid properties for computed fields"
- ❌ Do NOT suggest: "Consider switching to Tortoise ORM for async support"

## Behavioral Compatibility Notes

When suggesting changes, note potential behavioral impacts:

| # | Consideration |
|---|---------------|
| 1 | Would function/method signatures change? |
| 2 | Would return types or values be affected? |
| 3 | Would side effects be altered? |
| 4 | Would exception behavior change? |
| 5 | Would public attributes be affected? |

See `references/behavioral-compatibility.md` for detailed guidance.

## Concurrency Verification

These terms are NOT interchangeable—verify via WebSearch before making claims:

| Term | Meaning | Example |
|------|---------|---------|
| Async-safe | Safe for concurrent coroutines (single thread) | `asyncio.Lock()` |
| Thread-safe | Safe for concurrent threads | `threading.Lock()` |
| Process-safe | Safe across worker processes | Redis, database, file locks |

In-memory caches and locks do NOT provide safety across worker processes (e.g., uvicorn/gunicorn workers).

## Ambiguity Handling

When encountering ambiguous cases:
- Note the ambiguity in the report
- Present multiple possible interpretations if relevant
- Flag areas needing clarification with `<!-- CLARIFY: reason -->`
- When in doubt, acknowledge uncertainty in the analysis

## Additional Resources

### Reference Files

Consult for detailed guidance:
- **`references/project-type-profiles.md`** - Project type thresholds and filtering configuration
- **`references/design-principles.md`** - Complete SOLID, DRY, KISS, YAGNI guidance with Python examples
- **`references/modern-python.md`** - Modern Python features, type hints, dataclasses, idioms
- **`references/code-smells.md`** - Comprehensive code smell catalog with detection and fixes
- **`references/behavioral-compatibility.md`** - Detailed 13-point checklist with verification strategies

## Success Metrics

Analysis succeeds when:
- **Project type is identified** (from context or defaults to private)
- **Thresholds are applied** according to project type profile
- All provided documents are processed (or errors reported)
- Each document's code blocks are analyzed
- Explicit architectural decisions are recognized and respected
- Findings are presented as opportunities, not mandates
- Suggested alternatives are practical within stated constraints
- Report includes project type and analysis mode in header
- Report is comprehensive but actionable
- **No documents are modified**