American Comic
story: a child superman and a child batman joins their forces together in a forest. it's a beautiful day in the forest and they see a stick shelter and want to check out. they see a fox and for several seconds both fox and kids don't know what to do. they think first. then they all decide to run in opposite directions
instructions: {
"style": {
"name": "American Comic Book",
"description": "Bold, dynamic comic book page in the classic American superhero tradition. Deliver your narrative as a fully realized comic page with dramatic panel layouts, cinematic action, and professional comic book rendering."
},
"visual_foundation": {
"medium": {
"type": "Professional American comic book art",
"tradition": "DC/Marvel mainstream superhero comics",
"era": "Modern age (2000s-present) with classic sensibilities",
"finish": "Fully inked and digitally colored, publication-ready"
},
"page_presence": {
"impact": "Each page should feel like a splash-worthy moment",
"energy": "Kinetic, explosive, larger-than-life",
"tone": "Epic and dramatic, never static or mundane"
}
},
"panel_architecture": {
"layout_philosophy": {
"approach": "Dynamic asymmetrical grid with dramatic variation",
"pacing": "Panel sizes reflect story beats—big moments get big panels",
"flow": "Clear left-to-right, top-to-bottom reading path despite dynamic layout",
"gutters": "Clean white gutters, consistent width, sharp panel borders"
},
"panel_variety": {
"hero_panel": "Large central or full-width panel for key action moment",
"establishing": "Wide panels for scale and environment",
"reaction": "Smaller panels for faces, dialogue, tension beats",
"inset": "Occasional overlapping panels for emphasis or simultaneity"
},
"border_treatment": {
"standard": "Clean black rectangular borders",
"action_breaks": "Panel borders may shatter or be broken by explosive action",
"bleed": "Key moments may bleed to page edge for maximum impact"
}
},
"artistic_rendering": {
"line_work": {
"quality": "Bold, confident, professional inking",
"weight_variation": "Heavy outlines on figures, medium on details, fine for texture",
"contour": "Strong silhouettes readable at any size",
"hatching": "Strategic crosshatching for form and shadow, not overworked",
"energy_lines": "Speed lines, impact bursts, motion trails for kinetic action"
},
"anatomy_and_figures": {
"style": "Heroic idealized anatomy—powerful, dynamic, exaggerated",
"musculature": "Detailed muscle definition, anatomy pushed for drama",
"poses": "Extreme foreshortening, dramatic angles, impossible dynamism",
"scale": "Figures commanding space, heroic proportions",
"expression": "Intense, readable emotions even at distance"
},
"environmental_rendering": {
"destruction": "Detailed rubble, debris clouds, structural damage",
"atmosphere": "Rain, smoke, dust, particle effects for mood",
"architecture": "Solid perspective, detailed enough for scale reference",
"depth": "Clear foreground/midground/background separation"
}
},
"color_philosophy": {
"approach": {
"style": "Modern digital coloring with painterly rendering",
"depth": "Full modeling with highlights, midtones, shadows",
"mood": "Color supports emotional tone of each panel"
},
"palette_dynamics": {
"characters": "Bold, saturated colors for heroes/main figures",
"environments": "More muted, atmospheric tones to push figures forward",
"contrast": "Strong value contrast between subjects and backgrounds",
"temperature": "Strategic warm/cool contrast for depth and drama"
},
"atmospheric_coloring": {
"sky": "Dramatic gradients—stormy grays, apocalyptic oranges, moody blues",
"weather": "Rain rendered as white/light blue streaks against darker values",
"fire_energy": "Vibrant oranges, yellows with white-hot cores, proper glow falloff",
"smoke_dust": "Layered opacity, warm and cool grays mixing"
},
"lighting_effects": {
"key_light": "Strong dramatic source creating bold shadows",
"rim_light": "Edge lighting separating figures from backgrounds",
"energy_glow": "Bloom effects on power sources, eyes, weapons",
"environmental": "Bounce light from fires, explosions, energy blasts"
}
},
"typography_and_lettering": {
"speech_bubbles": {
"shape": "Classic oval/rounded rectangle balloons",
"border": "Clean black outline, consistent weight",
"tail": "Pointed tail clearly indicating speaker",
"fill": "Pure white interior for maximum readability"
},
"dialogue_text": {
"font": "Classic comic book lettering—bold, clean, uppercase",
"size": "Readable at print size, consistent throughout",
"emphasis": "Bold for stress, italics for whispers or thoughts"
},
"sound_effects": {
"style": "Large, dynamic, integrated into the art",
"design": "Custom lettering matching the sound—jagged for explosions, bold for impacts",
"color": "Vibrant colors with outlines, shadows, or 3D effects",
"placement": "Part of the composition, not just overlaid"
},
"captions": {
"style": "Rectangular boxes with subtle color coding",
"placement": "Top or bottom of panels, clear hierarchy"
}
},
"action_and_dynamics": {
"motion_rendering": {
"speed_lines": "Radiating or parallel lines showing movement direction",
"motion_blur": "Selective blur on fast-moving elements",
"impact_frames": "Starburst patterns at point of collision",
"debris_scatter": "Rocks, glass, rubble flying with clear trajectories"
},
"impact_visualization": {
"collision": "Visible shockwaves, ground cracks, structural deformation",
"energy_attacks": "Bright core fading to colored edges with atmospheric scatter",
"physical_force": "Bodies reacting realistically to impossible forces"
},
"camera_dynamics": {
"angles": "Extreme low angles for power, high angles for scale",
"foreshortening": "Aggressive perspective on approaching figures/fists",
"dutch_angles": "Tilted frames for tension and unease",
"depth_of_field": "Suggested focus through detail level and blur"
}
},
"atmospheric_elements": {
"weather": {
"rain": "Diagonal streaks, splashes on surfaces, wet reflections",
"lightning": "Bright forks illuminating scenes dramatically",
"wind": "Debris, hair, capes showing direction and force"
},
"destruction_aesthetic": {
"rubble": "Detailed concrete chunks, rebar, shattered glass",
"dust_clouds": "Billowing, layered, atmospheric perspective",
"fire": "Realistic flame shapes with proper color temperature gradient",
"smoke": "Rising columns, drifting wisps, obscuring backgrounds"
},
"scale_indicators": {
"buildings": "Damaged structures showing massive scale",
"vehicles": "Cars, tanks as size reference objects",
"crowds": "Smaller figures emphasizing main subject scale"
}
},
"technical_standards": {
"composition": {
"focal_point": "Clear visual hierarchy in every panel",
"eye_flow": "Deliberate path through panels via placement and contrast",
"balance": "Dynamic asymmetry that feels intentional, not chaotic"
},
"consistency": {
"character_models": "Consistent design across all panels",
"lighting_logic": "Light sources make sense across the page",
"scale_relationships": "Size ratios maintained throughout"
},
"print_ready": {
"resolution": "High resolution suitable for print reproduction",
"color_space": "Vibrant colors that work in CMYK",
"bleed_safe": "Important elements away from trim edges"
}
},
"page_composition": {
"no_border": {
"edge_treatment": "NO frame around the page—panels extend to image edge",
"bleed": "Page IS the comic page, not a picture of one",
"presentation": "Direct comic page, not photographed or framed"
}
},
"avoid": [
"Any frame or border around the entire page",
"Photograph-of-a-comic-page effect",
"Static, stiff poses without energy",
"Flat lighting without dramatic shadows",
"Muddy, desaturated coloring",
"Weak, scratchy, or inconsistent line work",
"Confusing panel flow or layout",
"Tiny unreadable lettering",
"Sound effects as plain text overlay",
"Anatomically incorrect figures (unless stylized intentionally)",
"Empty, boring backgrounds",
"Inconsistent character scale between panels",
"Manga-style effects in American comic aesthetic",
"Overly rendered to the point of losing graphic punch",
"Weak impact moments—every action should have weight"
]
}
Cinematic Ink & Color Illustration Generator — Gary Frank Style
{
"type": "illustration",
"goal": "Create a single wide cinematic illustration of a lone cowboy sitting on a wooden chair in front of an Old West saloon at dusk. Rendered with meticulous hand-inked linework over rich digitally-painted color. The technique combines bold black ink contour drawing with deep, layered, fully-rendered color work — the kind of dramatic realism found in high-end editorial illustration and graphic novel art.",
"work_surface": {
"type": "Single illustration, landscape orientation",
"aspect_ratio": "16:9 widescreen cinematic",
"medium": "Black ink line drawing with full digital color rendering — the line art has the confident hand-drawn quality of traditional inking, the color has the depth of oil-painting-influenced digital work"
},
"rendering_technique": {
"line_work": {
"tool_feel": "Traditional dip pen and brush ink on paper — confident, deliberate strokes with natural line weight variation. Not vector-clean, not scratchy-loose. The sweet spot of controlled precision with organic warmth.",
"outer_contours": "Bold black ink outlines (3-4pt equivalent) defining every figure and major object. These contour lines give the image its graphic punch — silhouettes read clearly even at thumbnail size.",
"interior_detail": "Finer ink lines (1-2pt) for facial features, leather stitching, wood grain, fabric folds, wrinkles, hair strands. This interior detail is what separates high-end illustration from simple cartoon — obsessive attention to surface texture and form.",
"spotted_blacks": "Large areas of solid black ink used strategically — deep shadows under the porch overhang, inside the hat brim, the darkest folds of the vest. These black shapes create dramatic graphic contrast and anchor the composition.",
"hatching": "Minimal. Where it appears (underside of porch ceiling, deep fabric creases), it is tight, controlled, parallel lines. Never loose or decorative. Shadows are primarily defined through color, not line hatching."
},
"color_work": {
"approach": "Fully rendered, multi-layered digital painting OVER the ink lines. Not flat fills. Not cel-shading. Every surface has continuous tonal gradation — as if each area was painted with the care of an oil study.",
"skin": "Multi-tonal. Warm tan base with cooler shadows under jawline and eye sockets, subtle red warmth on nose and sun-exposed cheekbones, precise highlights on brow ridge and cheekbone. Skin looks weathered and alive.",
"materials": "Each material rendered distinctly. Leather has a slight waxy sheen on smooth areas and matte roughness on worn patches. Denim shows a faint diagonal weave. Metal (buckle, gun, spurs) has sharp specular highlights. Wood shows grain pattern, dust accumulation, age patina. Cotton shirt has soft diffused light transmission.",
"shadow_color": "CRITICAL: Shadows are NOT just darker versions of the base color. They shift toward cool blue-violet (#2d2d44, #3a3555). A brown leather vest's shadow is not dark brown — it is dark brown with a blue-purple undertone. This color-shifting in shadows creates atmospheric depth and cinematic richness.",
"light_color": "Where direct sunset light hits, surfaces gain a warm amber-golden overlay (#FFD280, #E8A848). This is additive — the golden light sits on top of the local color, making sun-facing surfaces glow."
},
"detail_density": "Extremely high. The viewer should be able to zoom in and discover new details: individual nail heads in the porch planks, a specific pattern of cracks in the leather, the particular way dust has settled in the creases of the hat, a tiny nick in the whiskey glass rim, the wear pattern on the boot sole. This density of observed detail is what creates the feeling of a real place inhabited by a real person.",
"DO_NOT": [
"Do NOT use flat color fills — every surface needs tonal gradation",
"Do NOT use cel-shading or hard-edged color blocks",
"Do NOT use cartoon proportions or exaggeration",
"Do NOT use anime or manga rendering conventions",
"Do NOT use soft airbrush blending that erases the ink lines",
"Do NOT use watercolor transparency or bleeding edges",
"Do NOT use photorealistic rendering — the ink linework must remain visible and central",
"Do NOT use sketchy, rough, or unfinished-looking line quality",
"Do NOT use pastel or desaturated washed-out colors — the palette is rich and deep"
]
},
"color_palette": {
"sky": {
"upper": "#1a1a3e deep indigo — night approaching from above",
"middle": "#6B3A5E dusty purple-mauve transition",
"lower_horizon": "#E8A040 to #FF7B3A blazing amber-to-orange sunset glow"
},
"saloon_wood": {
"lit": "#A0784C warm aged timber catching sunset",
"shadow": "#5C3A20 dark brown under porch overhang",
"weathered": "#8B7355 grey-brown bleached planks"
},
"ground": {
"lit": "#D4B896 warm sandy dust in golden light",
"shadow": "#7A6550 cool brown where light doesn't reach"
},
"cowboy": {
"hat": "#6B5B4F dark dusty brown, lighter dusty edges #8B7B6F",
"skin": "#B8845A sun-weathered tan, #8B6B42 in deep creases",
"shirt": "#C8B8A0 faded off-white, yellowed with age and dust",
"vest": "#3C2A1A dark worn leather, near-black in deepest folds",
"jeans": "#4A5568 faded dark blue-grey denim, #7B8898 dusty highlights at knees",
"boots": "#5C3A20 dark leather, #8B6B42 scuff marks",
"buckle": "#D4A574 antique brass catching one sharp sunset point",
"gun_metal": "#4A4A4A dark steel, single sharp highlight line"
},
"light_sources": {
"sunset": "#FFD280 to #FF8C42 — dominant golden-hour warmth from left",
"saloon_interior": "#FFA040 amber oil-lamp glow from behind swinging doors"
}
},
"lighting": {
"concept": "Golden hour — the sun sits just above the horizon to the left. Nearly horizontal rays of warm amber light rake across the scene. Every raised surface catches fire. Every shadow stretches long. The air itself has visible warmth. This is the most dramatic natural lighting condition — treated here with the gravity of a Renaissance chiaroscuro painting translated into ink and color.",
"key_light": {
"source": "Setting sun, low on horizon, from the left",
"color": "#FFD280 warm amber-gold",
"direction": "Nearly horizontal, raking from left to right",
"effect_on_cowboy": "Right side of face and body warmly lit — every weathered wrinkle, every thread of stubble visible in the golden light. Left side falls into cool blue-violet shadow. Creates a dramatic half-lit, half-shadow portrait.",
"effect_on_environment": "Long shadows stretching to the right across dusty ground. Sun-facing wood surfaces glow amber. Dust particles in the air catch light like floating golden sparks."
},
"fill_light": {
"source": "Ambient sky light from the dusk sky above",
"color": "#6B7B9B cool blue-purple",
"effect": "Fills shadow areas with cool tone. Prevents pure black — you see detail in shadows, but it's all tinted blue-violet. This warm/cool contrast between key and fill is what creates the richness."
},
"accent_light": {
"source": "Oil lamp glow from inside the saloon, spilling through swinging doors and windows",
"color": "#FFA040 warm amber",
"effect": "Rim light on the back of cowboy's hat and shoulders. Separates him from background. Also casts geometric window-light rectangles on the porch floor."
},
"shadow_treatment": {
"coverage": "45-55% of image area in shadow",
"cast_shadows": "Cowboy's long shadow stretches right across the street. Porch overhang throws a hard horizontal shadow across the saloon facade. Chair legs cast thin shadow lines.",
"face_shadows": "Half-face lighting. Right side warm and detailed. Left side cool shadow — eye socket deep, cheekbone creates a sharp shadow edge, stubble dots visible in the light-to-shadow transition.",
"atmospheric": "Visible dust motes floating in the sunset light beams. Golden in the light, invisible in the shadow. Creates a sense of thick warm air."
}
},
"scene": {
"composition": "Wide cinematic frame. The cowboy sits slightly left of center — the golden ratio point. The saloon facade fills the right two-thirds of the background. Open dusty street stretches left toward the horizon and setting sun. This asymmetry — solid structure on the right, open emptiness on the left — reinforces the emotional isolation. A single figure at the boundary between civilization (the saloon) and wilderness (the open desert).",
"the_cowboy": {
"position": "Seated on a rough wooden chair on the saloon's front porch",
"pose": "Leaned back, weight on the chair's hind legs. Left boot flat on porch floor. Right ankle crossed over left knee — easy, unhurried. Right hand loosely holds a short whiskey glass resting on his right knee. The glass is half-empty. Left hand rests on the chair arm or thigh. Head tilted very slightly down, but eyes aimed forward at the horizon — the thousand-yard stare of accumulated experience. Shoulders broad but not tensed. The body language says: I am at rest, but I am never unaware.",
"face": "This must be a SPECIFIC face, not a generic cowboy. Middle-aged, 40s-50s. Square jaw with defined jawline visible through the stubble. Deep-set eyes under a heavy brow ridge — intense, observant, slightly narrowed against the sunset glare. Three-day stubble, dark with threads of grey at the chin. Sun-weathered skin — deep crow's feet radiating from eye corners, horizontal forehead creases, nasolabial folds that have become permanent grooves. A healed scar across the left cheekbone — thin, white, old. Nose slightly crooked from a long-ago break, a bump on the bridge. Thin lips set in a neutral line — not a frown, not a smile. This face has lived decades of hard outdoor life and it shows in every crease.",
"clothing_detail": "Wide-brimmed cowboy hat, dark dusty brown, battered — dents in the crown, brim slightly curled and frayed at edges, a sweat stain ring visible on the band. Faded off-white cotton shirt, sleeves rolled to mid-forearm exposing sun-tanned forearms with visible veins and tendons. Dark leather vest over the shirt, well-worn — surface cracked in places, stitching visible at seams, a few spots where the leather has gone matte from years of use. Faded dark blue-grey jeans, lighter at the knees and thighs from wear, dusty. Wide leather belt with an antique brass buckle — the buckle catches one sharp point of sunset light. Holstered revolver on the right hip — dark aged leather holster, the wooden pistol grip visible, a glint of steel. Dark brown leather boots, scuffed and scored, heels slightly worn down, spur straps buckled at the ankle."
},
"the_saloon": {
"architecture": "Classic Old West frontier saloon. Two-story wooden building with a false front (the facade extends above the actual roofline to make it look grander). Built from rough-sawn timber planks, some warped with age. A painted sign above the entrance: 'SALOON' in faded gold lettering on a dark red background — the paint is cracking, peeling at the corners, one letter slightly more faded than the others.",
"entrance": "Swinging batwing doors at the center, slightly ajar. Through the gap, warm amber light spills outward — the glow of oil lamps and activity inside. You don't see the interior clearly, just the suggestion of warmth and noise contained behind those doors.",
"windows": "Two windows flanking the entrance. Dirty glass with a warm glow from inside. One pane has a crack running diagonally across it.",
"porch": "Wooden porch running the width of the building. Planks are weathered — grey where the sun has bleached them, darker brown where foot traffic has worn them smooth. Some boards slightly warped, a few nail heads protruding. Rough-hewn timber posts support the porch overhang.",
"details": "A hitching post in front with a horse's lead rope tied to it — the rope is taut, suggesting an animal just out of frame. A wooden water trough near the hitching post, its surface greenish. A barrel beside the door. Everything covered in a thin layer of desert dust."
},
"constraints": {
"must_include": [
"Bold black ink contour lines visible throughout — this is line art with color, not a painting",
"Rich multi-layered color with tonal gradation on every surface",
"Cool blue-violet shift in all shadow areas (not just darkened base color)",
"Warm amber-golden light where sunset hits directly",
"Extremely detailed face with specific individual features — scars, wrinkles, bone structure",
"Material differentiation — leather, wood, metal, fabric, skin all look different",
"Atmospheric dust particles in sunset light beams",
"Long dramatic cast shadows on dusty ground",
"Warm glow from saloon interior as rim/accent light",
"Vast open space on left contrasting with solid saloon structure on right"
],
"must_avoid": [
"Cartoon or caricature style of any kind",
"Anime or manga rendering conventions",
"Flat color fills without gradation",
"Soft airbrush that hides the ink linework",
"Photographic realism — the ink drawing must be visible",
"Generic featureless face — this must be a specific person",
"Clean or new-looking anything — everything shows age and wear",
"Muddy dark coloring — the sunset provides rich warm light",
"Stiff posed figure — natural relaxed human body language",
"Watercolor transparency or bleeding-edge technique"
]
},
"negative_prompt": "anime, manga, chibi, cartoon, caricature, flat colors, cel-shading, minimalist, photorealistic photograph, 3D CGI render, soft airbrush, watercolor, pastel colors, sketchy rough lines, generic face, clean new clothing, bright neon, blurry, low resolution, stiff pose, modern elements, vector art, simple illustration, children's book style, pop art, abstract"
}
Comprehensive Python Codebase Review - Forensic-Level Analysis Prompt
# COMPREHENSIVE PYTHON CODEBASE REVIEW
You are an expert Python code reviewer with 20+ years of experience in enterprise software development, security auditing, and performance optimization. Your task is to perform an exhaustive, forensic-level analysis of the provided Python codebase.
## REVIEW PHILOSOPHY
- Assume nothing is correct until proven otherwise
- Every line of code is a potential source of bugs
- Every dependency is a potential security risk
- Every function is a potential performance bottleneck
- Every mutable default is a ticking time bomb
- Every `except` block is potentially swallowing critical errors
- Dynamic typing means runtime surprises — treat every untyped function as suspect
---
## 1. TYPE SYSTEM & TYPE HINTS ANALYSIS
### 1.1 Type Annotation Coverage
- [ ] Identify ALL functions/methods missing type hints (parameters and return types)
- [ ] Find `Any` type usage — each one bypasses type checking entirely
- [ ] Detect `# type: ignore` comments — each one is hiding a potential bug
- [ ] Find `cast()` calls that could fail at runtime
- [ ] Identify `TYPE_CHECKING` imports used incorrectly (circular import hacks)
- [ ] Check for `__all__` missing in public modules
- [ ] Find `Union` types that should be narrower
- [ ] Detect `Optional` parameters without `None` default values
- [ ] Identify `dict`, `list`, `tuple` used without generic subscript (`dict[str, int]`)
- [ ] Check for `TypeVar` without proper bounds or constraints
### 1.2 Type Correctness
- [ ] Find `isinstance()` checks that miss subtypes or union members
- [ ] Identify `type()` comparison instead of `isinstance()` (breaks inheritance)
- [ ] Detect `hasattr()` used for type checking instead of protocols/ABCs
- [ ] Find string-based type references that could break (`"ClassName"` forward refs)
- [ ] Identify `typing.Protocol` that should exist but doesn't
- [ ] Check for `@overload` decorators missing for polymorphic functions
- [ ] Find `TypedDict` with missing `total=False` for optional keys
- [ ] Detect `NamedTuple` fields without types
- [ ] Identify `dataclass` fields with mutable default values (use `field(default_factory=...)`)
- [ ] Check for `Literal` types that should be used for string enums
### 1.3 Runtime Type Validation
- [ ] Find public API functions without runtime input validation
- [ ] Identify missing Pydantic/attrs/dataclass validation at boundaries
- [ ] Detect `json.loads()` results used without schema validation
- [ ] Find API request/response bodies without model validation
- [ ] Identify environment variables used without type coercion and validation
- [ ] Check for proper use of `TypeGuard` for type narrowing functions
- [ ] Find places where `typing.assert_type()` (3.11+) should be used
---
## 2. NONE / SENTINEL HANDLING
### 2.1 None Safety
- [ ] Find ALL places where `None` could occur but isn't handled
- [ ] Identify `dict.get()` return values used without None checks
- [ ] Detect `dict[key]` access that could raise `KeyError`
- [ ] Find `list[index]` access without bounds checking (`IndexError`)
- [ ] Identify `re.match()` / `re.search()` results used without None checks
- [ ] Check for `next(iterator)` without default parameter (`StopIteration`)
- [ ] Find `os.environ.get()` used without fallback where value is required
- [ ] Detect attribute access on potentially None objects
- [ ] Identify `Optional[T]` return types where callers don't check for None
- [ ] Find chained attribute access (`a.b.c.d`) without intermediate None checks
### 2.2 Mutable Default Arguments
- [ ] Find ALL mutable default parameters (`def foo(items=[])`) — CRITICAL BUG
- [ ] Identify `def foo(data={})` — shared dict across calls
- [ ] Detect `def foo(callbacks=[])` — list accumulates across calls
- [ ] Find `def foo(config=SomeClass())` — shared instance
- [ ] Check for mutable class-level attributes shared across instances
- [ ] Identify `dataclass` fields with mutable defaults (need `field(default_factory=...)`)
### 2.3 Sentinel Values
- [ ] Find `None` used as sentinel where a dedicated sentinel object should be used
- [ ] Identify functions where `None` is both a valid value and "not provided"
- [ ] Detect `""` or `0` or `False` used as sentinel (conflicts with legitimate values)
- [ ] Find `_MISSING = object()` sentinels without proper `__repr__`
---
## 3. ERROR HANDLING ANALYSIS
### 3.1 Exception Handling Patterns
- [ ] Find bare `except:` clauses — catches `SystemExit`, `KeyboardInterrupt`, `GeneratorExit`
- [ ] Identify `except Exception:` that swallows errors silently
- [ ] Detect `except` blocks with only `pass` — silent failure
- [ ] Find `except` blocks that catch too broadly (`except (Exception, BaseException):`)
- [ ] Identify `except` blocks that don't log or re-raise
- [ ] Check for `except Exception as e:` where `e` is never used
- [ ] Find `raise` without `from` losing original traceback (`raise NewError from original`)
- [ ] Detect exception handling in `__del__` (dangerous — interpreter may be shutting down)
- [ ] Identify `try` blocks that are too large (should be minimal)
- [ ] Check for proper exception chaining with `__cause__` and `__context__`
### 3.2 Custom Exceptions
- [ ] Find raw `Exception` / `ValueError` / `RuntimeError` raised instead of custom types
- [ ] Identify missing exception hierarchy for the project
- [ ] Detect exception classes without proper `__init__` (losing args)
- [ ] Find error messages that leak sensitive information
- [ ] Identify missing `__str__` / `__repr__` on custom exceptions
- [ ] Check for proper exception module organization (`exceptions.py`)
### 3.3 Context Managers & Cleanup
- [ ] Find resource acquisition without `with` statement (files, locks, connections)
- [ ] Identify `open()` without `with` — potential file handle leak
- [ ] Detect `__enter__` / `__exit__` implementations that don't handle exceptions properly
- [ ] Find `__exit__` returning `True` (suppressing exceptions) without clear intent
- [ ] Identify missing `contextlib.suppress()` for expected exceptions
- [ ] Check for nested `with` statements that could use `contextlib.ExitStack`
- [ ] Find database transactions without proper commit/rollback in context manager
- [ ] Detect `tempfile.NamedTemporaryFile` without cleanup
- [ ] Identify `threading.Lock` acquisition without `with` statement
---
## 4. ASYNC / CONCURRENCY
### 4.1 Asyncio Issues
- [ ] Find `async` functions that never `await` (should be regular functions)
- [ ] Identify missing `await` on coroutines (coroutine never executed — just created)
- [ ] Detect `asyncio.run()` called from within running event loop
- [ ] Find blocking calls inside `async` functions (`time.sleep`, sync I/O, CPU-bound)
- [ ] Identify `loop.run_in_executor()` missing for blocking operations in async code
- [ ] Check for `asyncio.gather()` without `return_exceptions=True` where appropriate
- [ ] Find `asyncio.create_task()` without storing reference (task could be GC'd)
- [ ] Detect `async for` / `async with` misuse
- [ ] Identify missing `asyncio.shield()` for operations that shouldn't be cancelled
- [ ] Check for proper `asyncio.TaskGroup` usage (Python 3.11+)
- [ ] Find event loop created per-request instead of reusing
- [ ] Detect `asyncio.wait()` without proper `return_when` parameter
### 4.2 Threading Issues
- [ ] Find shared mutable state without `threading.Lock`
- [ ] Identify GIL assumptions for thread safety (only protects Python bytecode, not C extensions)
- [ ] Detect `threading.Thread` started without `daemon=True` or proper join
- [ ] Find thread-local storage misuse (`threading.local()`)
- [ ] Identify missing `threading.Event` for thread coordination
- [ ] Check for deadlock risks (multiple locks acquired in different orders)
- [ ] Find `queue.Queue` timeout handling missing
- [ ] Detect thread pool (`ThreadPoolExecutor`) without `max_workers` limit
- [ ] Identify non-thread-safe operations on shared collections
- [ ] Check for proper `concurrent.futures` usage with error handling
### 4.3 Multiprocessing Issues
- [ ] Find objects that can't be pickled passed to multiprocessing
- [ ] Identify `multiprocessing.Pool` without proper `close()`/`join()`
- [ ] Detect shared state between processes without `multiprocessing.Manager` or `Value`/`Array`
- [ ] Find `fork` mode issues on macOS (use `spawn` instead)
- [ ] Identify missing `if __name__ == "__main__":` guard for multiprocessing
- [ ] Check for large objects being serialized/deserialized between processes
- [ ] Find zombie processes not being reaped
### 4.4 Race Conditions
- [ ] Find check-then-act patterns without synchronization
- [ ] Identify file operations with TOCTOU vulnerabilities
- [ ] Detect counter increments without atomic operations
- [ ] Find cache operations (read-modify-write) without locking
- [ ] Identify signal handler race conditions
- [ ] Check for `dict`/`list` modifications during iteration from another thread
---
## 5. RESOURCE MANAGEMENT
### 5.1 Memory Management
- [ ] Find large data structures kept in memory unnecessarily
- [ ] Identify generators/iterators not used where they should be (loading all into list)
- [ ] Detect `list(huge_generator)` materializing unnecessarily
- [ ] Find circular references preventing garbage collection
- [ ] Identify `__del__` methods that could prevent GC (prevent reference cycles from being collected)
- [ ] Check for large global variables that persist for process lifetime
- [ ] Find string concatenation in loops (`+=`) instead of `"".join()` or `io.StringIO`
- [ ] Detect `copy.deepcopy()` on large objects in hot paths
- [ ] Identify `pandas.DataFrame` copies where in-place operations suffice
- [ ] Check for `__slots__` missing on classes with many instances
- [ ] Find caches (`dict`, `lru_cache`) without size limits — unbounded memory growth
- [ ] Detect `functools.lru_cache` on methods (holds reference to `self` — memory leak)
### 5.2 File & I/O Resources
- [ ] Find `open()` without `with` statement
- [ ] Identify missing file encoding specification (`open(f, encoding="utf-8")`)
- [ ] Detect `read()` on potentially huge files (use `readline()` or chunked reading)
- [ ] Find temporary files not cleaned up (`tempfile` without context manager)
- [ ] Identify file descriptors not being closed in error paths
- [ ] Check for missing `flush()` / `fsync()` for critical writes
- [ ] Find `os.path` usage where `pathlib.Path` is cleaner
- [ ] Detect file permissions too permissive (`os.chmod(path, 0o777)`)
### 5.3 Network & Connection Resources
- [ ] Find HTTP sessions not reused (`requests.get()` per call instead of `Session`)
- [ ] Identify database connections not returned to pool
- [ ] Detect socket connections without timeout
- [ ] Find missing `finally` / context manager for connection cleanup
- [ ] Identify connection pool exhaustion risks
- [ ] Check for DNS resolution caching issues in long-running processes
- [ ] Find `urllib`/`requests` without timeout parameter (hangs indefinitely)
---
## 6. SECURITY VULNERABILITIES
### 6.1 Injection Attacks
- [ ] Find SQL queries built with f-strings or `%` formatting (SQL injection)
- [ ] Identify `os.system()` / `subprocess.call(shell=True)` with user input (command injection)
- [ ] Detect `eval()` / `exec()` usage — CRITICAL security risk
- [ ] Find `pickle.loads()` on untrusted data (arbitrary code execution)
- [ ] Identify `yaml.load()` without `Loader=SafeLoader` (code execution)
- [ ] Check for `jinja2` templates without autoescape (XSS)
- [ ] Find `xml.etree` / `xml.dom` without defusing (XXE attacks) — use `defusedxml`
- [ ] Detect `__import__()` / `importlib` with user-controlled module names
- [ ] Identify `input()` in Python 2 (evaluates expressions) — if maintaining legacy code
- [ ] Find `marshal.loads()` on untrusted data
- [ ] Check for `shelve` / `dbm` with user-controlled keys
- [ ] Detect path traversal via `os.path.join()` with user input without validation
- [ ] Identify SSRF via user-controlled URLs in `requests.get()`
- [ ] Find `ast.literal_eval()` used as sanitization (not sufficient for all cases)
### 6.2 Authentication & Authorization
- [ ] Find hardcoded credentials, API keys, tokens, or secrets in source code
- [ ] Identify missing authentication decorators on protected views/endpoints
- [ ] Detect authorization bypass possibilities (IDOR)
- [ ] Find JWT implementation flaws (algorithm confusion, missing expiry validation)
- [ ] Identify timing attacks in string comparison (`==` vs `hmac.compare_digest`)
- [ ] Check for proper password hashing (`bcrypt`, `argon2` — NOT `hashlib.md5/sha256`)
- [ ] Find session tokens with insufficient entropy (`random` vs `secrets`)
- [ ] Detect privilege escalation paths
- [ ] Identify missing CSRF protection (Django `@csrf_exempt` overuse, Flask-WTF missing)
- [ ] Check for proper OAuth2 implementation
### 6.3 Cryptographic Issues
- [ ] Find `random` module used for security purposes (use `secrets` module)
- [ ] Identify weak hash algorithms (`md5`, `sha1`) for security operations
- [ ] Detect hardcoded encryption keys/IVs/salts
- [ ] Find ECB mode usage in encryption
- [ ] Identify `ssl` context with `check_hostname=False` or custom `verify=False`
- [ ] Check for `requests.get(url, verify=False)` — disables TLS verification
- [ ] Find deprecated crypto libraries (`PyCrypto` → use `cryptography` or `PyCryptodome`)
- [ ] Detect insufficient key lengths
- [ ] Identify missing HMAC for message authentication
### 6.4 Data Security
- [ ] Find sensitive data in logs (`logging.info(f"Password: {password}")`)
- [ ] Identify PII in exception messages or tracebacks
- [ ] Detect sensitive data in URL query parameters
- [ ] Find `DEBUG = True` in production configuration
- [ ] Identify Django `SECRET_KEY` hardcoded or committed
- [ ] Check for `ALLOWED_HOSTS = ["*"]` in Django
- [ ] Find sensitive data serialized to JSON responses
- [ ] Detect missing security headers (CSP, HSTS, X-Frame-Options)
- [ ] Identify `CORS_ALLOW_ALL_ORIGINS = True` in production
- [ ] Check for proper cookie flags (`secure`, `httponly`, `samesite`)
### 6.5 Dependency Security
- [ ] Run `pip audit` / `safety check` — analyze all vulnerabilities
- [ ] Check for dependencies with known CVEs
- [ ] Identify abandoned/unmaintained dependencies (last commit >2 years)
- [ ] Find dependencies installed from non-PyPI sources (git URLs, local paths)
- [ ] Check for unpinned dependency versions (`requests` vs `requests==2.31.0`)
- [ ] Identify `setup.py` with `install_requires` using `>=` without upper bound
- [ ] Find typosquatting risks in dependency names
- [ ] Check for `requirements.txt` vs `pyproject.toml` consistency
- [ ] Detect `pip install --trusted-host` or `--index-url` pointing to non-HTTPS sources
---
## 7. PERFORMANCE ANALYSIS
### 7.1 Algorithmic Complexity
- [ ] Find O(n²) or worse algorithms (`for x in list: if x in other_list`)
- [ ] Identify `list` used for membership testing where `set` gives O(1)
- [ ] Detect nested loops that could be flattened with `itertools`
- [ ] Find repeated iterations that could be combined into single pass
- [ ] Identify sorting operations that could be avoided (`heapq` for top-k)
- [ ] Check for unnecessary list copies (`sorted()` vs `.sort()`)
- [ ] Find recursive functions without memoization (`@functools.lru_cache`)
- [ ] Detect quadratic string operations (`str += str` in loop)
### 7.2 Python-Specific Performance
- [ ] Find list comprehension opportunities replacing `for` + `append`
- [ ] Identify `dict`/`set` comprehension opportunities
- [ ] Detect generator expressions that should replace list comprehensions (memory)
- [ ] Find `in` operator on `list` where `set` lookup is O(1)
- [ ] Identify `global` variable access in hot loops (slower than local)
- [ ] Check for attribute access in tight loops (`self.x` — cache to local variable)
- [ ] Find `len()` called repeatedly in loops instead of caching
- [ ] Detect `try/except` in hot path where `if` check is faster (LBYL vs EAFP trade-off)
- [ ] Identify `re.compile()` called inside functions instead of module level
- [ ] Check for `datetime.now()` called in tight loops
- [ ] Find `json.dumps()`/`json.loads()` in hot paths (consider `orjson`/`ujson`)
- [ ] Detect f-string formatting in logging calls that execute even when level is disabled
- [ ] Identify `**kwargs` unpacking in hot paths (dict creation overhead)
- [ ] Find unnecessary `list()` wrapping of iterators that are only iterated once
### 7.3 I/O Performance
- [ ] Find synchronous I/O in async code paths
- [ ] Identify missing connection pooling (`requests.Session`, `aiohttp.ClientSession`)
- [ ] Detect missing buffered I/O for large file operations
- [ ] Find N+1 query problems in ORM usage (Django `select_related`/`prefetch_related`)
- [ ] Identify missing database query optimization (missing indexes, full table scans)
- [ ] Check for `pandas.read_csv()` without `dtype` specification (slow type inference)
- [ ] Find missing pagination for large querysets
- [ ] Detect `os.listdir()` / `os.walk()` on huge directories without filtering
- [ ] Identify missing `__slots__` on data classes with millions of instances
- [ ] Check for proper use of `mmap` for large file processing
### 7.4 GIL & CPU-Bound Performance
- [ ] Find CPU-bound code running in threads (GIL prevents true parallelism)
- [ ] Identify missing `multiprocessing` for CPU-bound tasks
- [ ] Detect NumPy operations that release GIL not being parallelized
- [ ] Find `ProcessPoolExecutor` opportunities for CPU-intensive operations
- [ ] Identify C extension / Cython / Rust (PyO3) opportunities for hot loops
- [ ] Check for proper `asyncio.to_thread()` usage for blocking I/O in async code
---
## 8. CODE QUALITY ISSUES
### 8.1 Dead Code Detection
- [ ] Find unused imports (run `autoflake` or `ruff` check)
- [ ] Identify unreachable code after `return`/`raise`/`sys.exit()`
- [ ] Detect unused function parameters
- [ ] Find unused class attributes/methods
- [ ] Identify unused variables (especially in comprehensions)
- [ ] Check for commented-out code blocks
- [ ] Find unused exception variables in `except` clauses
- [ ] Detect feature flags for removed features
- [ ] Identify unused `__init__.py` imports
- [ ] Find orphaned test utilities/fixtures
### 8.2 Code Duplication
- [ ] Find duplicate function implementations across modules
- [ ] Identify copy-pasted code blocks with minor variations
- [ ] Detect similar logic that could be abstracted into shared utilities
- [ ] Find duplicate class definitions
- [ ] Identify repeated validation logic that could be decorators/middleware
- [ ] Check for duplicate error handling patterns
- [ ] Find similar API endpoint implementations that could be generalized
- [ ] Detect duplicate constants across modules
### 8.3 Code Smells
- [ ] Find functions longer than 50 lines
- [ ] Identify files larger than 500 lines
- [ ] Detect deeply nested conditionals (>3 levels) — use early returns / guard clauses
- [ ] Find functions with too many parameters (>5) — use dataclass/TypedDict config
- [ ] Identify God classes/modules with too many responsibilities
- [ ] Check for `if/elif/elif/...` chains that should be dict dispatch or match/case
- [ ] Find boolean parameters that should be separate functions or enums
- [ ] Detect `*args, **kwargs` passthrough that hides actual API
- [ ] Identify data clumps (groups of parameters that appear together)
- [ ] Find speculative generality (ABC/Protocol not actually subclassed)
### 8.4 Python Idioms & Style
- [ ] Find non-Pythonic patterns (`range(len(x))` instead of `enumerate`)
- [ ] Identify `dict.keys()` used unnecessarily (`if key in dict` works directly)
- [ ] Detect manual loop variable tracking instead of `enumerate()`
- [ ] Find `type(x) == SomeType` instead of `isinstance(x, SomeType)`
- [ ] Identify `== True` / `== False` / `== None` instead of `is`
- [ ] Check for `not x in y` instead of `x not in y`
- [ ] Find `lambda` assigned to variable (use `def` instead)
- [ ] Detect `map()`/`filter()` where comprehension is clearer
- [ ] Identify `from module import *` (pollutes namespace)
- [ ] Check for `except:` without exception type (catches everything including SystemExit)
- [ ] Find `__init__.py` with too much code (should be minimal re-exports)
- [ ] Detect `print()` statements used for debugging (use `logging`)
- [ ] Identify string formatting inconsistency (f-strings vs `.format()` vs `%`)
- [ ] Check for `os.path` when `pathlib` is cleaner
- [ ] Find `dict()` constructor where `{}` literal is idiomatic
- [ ] Detect `if len(x) == 0:` instead of `if not x:`
### 8.5 Naming Issues
- [ ] Find variables not following `snake_case` convention
- [ ] Identify classes not following `PascalCase` convention
- [ ] Detect constants not following `UPPER_SNAKE_CASE` convention
- [ ] Find misleading variable/function names
- [ ] Identify single-letter variable names (except `i`, `j`, `k`, `x`, `y`, `_`)
- [ ] Check for names that shadow builtins (`id`, `type`, `list`, `dict`, `input`, `open`, `file`, `format`, `range`, `map`, `filter`, `set`, `str`, `int`)
- [ ] Find private attributes without leading underscore where appropriate
- [ ] Detect overly abbreviated names that reduce readability
- [ ] Identify `cls` not used for classmethod first parameter
- [ ] Check for `self` not used as first parameter in instance methods
---
## 9. ARCHITECTURE & DESIGN
### 9.1 Module & Package Structure
- [ ] Find circular imports between modules
- [ ] Identify import cycles hidden by lazy imports
- [ ] Detect monolithic modules that should be split into packages
- [ ] Find improper layering (views importing models directly, bypassing services)
- [ ] Identify missing `__init__.py` public API definition
- [ ] Check for proper separation: domain, service, repository, API layers
- [ ] Find shared mutable global state across modules
- [ ] Detect relative imports where absolute should be used (or vice versa)
- [ ] Identify `sys.path` manipulation hacks
- [ ] Check for proper namespace package usage
### 9.2 SOLID Principles
- [ ] **Single Responsibility**: Find modules/classes doing too much
- [ ] **Open/Closed**: Find code requiring modification for extension (missing plugin/hook system)
- [ ] **Liskov Substitution**: Find subclasses that break parent class contracts
- [ ] **Interface Segregation**: Find ABCs/Protocols with too many required methods
- [ ] **Dependency Inversion**: Find concrete class dependencies where Protocol/ABC should be used
### 9.3 Design Patterns
- [ ] Find missing Factory pattern for complex object creation
- [ ] Identify missing Strategy pattern (behavior variation via callable/Protocol)
- [ ] Detect missing Repository pattern for data access abstraction
- [ ] Find Singleton anti-pattern (use dependency injection instead)
- [ ] Identify missing Decorator pattern for cross-cutting concerns
- [ ] Check for proper Observer/Event pattern (not hardcoding notifications)
- [ ] Find missing Builder pattern for complex configuration
- [ ] Detect missing Command pattern for undoable/queueable operations
- [ ] Identify places where `__init_subclass__` or metaclass could reduce boilerplate
- [ ] Check for proper use of ABC vs Protocol (nominal vs structural typing)
### 9.4 Framework-Specific (Django/Flask/FastAPI)
- [ ] Find fat views/routes with business logic (should be in service layer)
- [ ] Identify missing middleware for cross-cutting concerns
- [ ] Detect N+1 queries in ORM usage
- [ ] Find raw SQL where ORM query is sufficient (and vice versa)
- [ ] Identify missing database migrations
- [ ] Check for proper serializer/schema validation at API boundaries
- [ ] Find missing rate limiting on public endpoints
- [ ] Detect missing API versioning strategy
- [ ] Identify missing health check / readiness endpoints
- [ ] Check for proper signal/hook usage instead of monkeypatching
---
## 10. DEPENDENCY ANALYSIS
### 10.1 Version & Compatibility Analysis
- [ ] Check all dependencies for available updates
- [ ] Find unpinned versions in `requirements.txt` / `pyproject.toml`
- [ ] Identify `>=` without upper bound constraints
- [ ] Check Python version compatibility (`python_requires` in `pyproject.toml`)
- [ ] Find conflicting dependency versions
- [ ] Identify dependencies that should be in `dev` / `test` groups only
- [ ] Check for `requirements.txt` generated from `pip freeze` with unnecessary transitive deps
- [ ] Find missing `extras_require` / optional dependency groups
- [ ] Detect `setup.py` that should be migrated to `pyproject.toml`
### 10.2 Dependency Health
- [ ] Check last release date for each dependency
- [ ] Identify archived/unmaintained dependencies
- [ ] Find dependencies with open critical security issues
- [ ] Check for dependencies without type stubs (`py.typed` or `types-*` packages)
- [ ] Identify heavy dependencies that could be replaced with stdlib
- [ ] Find dependencies with restrictive licenses (GPL in MIT project)
- [ ] Check for dependencies with native C extensions (portability concern)
- [ ] Identify dependencies pulling massive transitive trees
- [ ] Find vendored code that should be a proper dependency
### 10.3 Virtual Environment & Packaging
- [ ] Check for proper `pyproject.toml` configuration
- [ ] Verify `setup.cfg` / `setup.py` is modern and complete
- [ ] Find missing `py.typed` marker for typed packages
- [ ] Check for proper entry points / console scripts
- [ ] Identify missing `MANIFEST.in` for sdist packaging
- [ ] Verify proper build backend (`setuptools`, `hatchling`, `flit`, `poetry`)
- [ ] Check for `pip install -e .` compatibility (editable installs)
- [ ] Find Docker images not using multi-stage builds for Python
---
## 11. TESTING GAPS
### 11.1 Coverage Analysis
- [ ] Run `pytest --cov` — identify untested modules and functions
- [ ] Find untested error/exception paths
- [ ] Detect untested edge cases in conditionals
- [ ] Check for missing boundary value tests
- [ ] Identify untested async code paths
- [ ] Find untested input validation scenarios
- [ ] Check for missing integration tests (database, HTTP, external services)
- [ ] Identify critical business logic without property-based tests (`hypothesis`)
### 11.2 Test Quality
- [ ] Find tests that don't assert anything meaningful (`assert True`)
- [ ] Identify tests with excessive mocking hiding real bugs
- [ ] Detect tests that test implementation instead of behavior
- [ ] Find tests with shared mutable state (execution order dependent)
- [ ] Identify missing `pytest.mark.parametrize` for data-driven tests
- [ ] Check for flaky tests (timing-dependent, network-dependent)
- [ ] Find `@pytest.fixture` with wrong scope (leaking state between tests)
- [ ] Detect tests that modify global state without cleanup
- [ ] Identify `unittest.mock.patch` that mocks too broadly
- [ ] Check for `monkeypatch` cleanup in pytest fixtures
- [ ] Find missing `conftest.py` organization
- [ ] Detect `assert x == y` on floats without `pytest.approx()`
### 11.3 Test Infrastructure
- [ ] Find missing `conftest.py` for shared fixtures
- [ ] Identify missing test markers (`@pytest.mark.slow`, `@pytest.mark.integration`)
- [ ] Detect missing `pytest.ini` / `pyproject.toml [tool.pytest]` configuration
- [ ] Check for proper test database/fixture management
- [ ] Find tests relying on external services without mocks (fragile)
- [ ] Identify missing `factory_boy` or `faker` for test data generation
- [ ] Check for proper `vcr`/`responses`/`httpx_mock` for HTTP mocking
- [ ] Find missing snapshot/golden testing for complex outputs
- [ ] Detect missing type checking in CI (`mypy --strict` or `pyright`)
- [ ] Identify missing `pre-commit` hooks configuration
---
## 12. CONFIGURATION & ENVIRONMENT
### 12.1 Python Configuration
- [ ] Check `pyproject.toml` is properly configured
- [ ] Verify `mypy` / `pyright` configuration with strict mode
- [ ] Check `ruff` / `flake8` configuration with appropriate rules
- [ ] Verify `black` / `ruff format` configuration for consistent formatting
- [ ] Check `isort` / `ruff` import sorting configuration
- [ ] Verify Python version pinning (`.python-version`, `Dockerfile`)
- [ ] Check for proper `__init__.py` structure in all packages
- [ ] Find `sys.path` manipulation that should be proper package installs
### 12.2 Environment Handling
- [ ] Find hardcoded environment-specific values (URLs, ports, paths, database URLs)
- [ ] Identify missing environment variable validation at startup
- [ ] Detect improper fallback values for missing config
- [ ] Check for proper `.env` file handling (`python-dotenv`, `pydantic-settings`)
- [ ] Find sensitive values not using secrets management
- [ ] Identify `DEBUG=True` accessible in production
- [ ] Check for proper logging configuration (level, format, handlers)
- [ ] Find `print()` statements that should be `logging`
### 12.3 Deployment Configuration
- [ ] Check Dockerfile follows best practices (non-root user, multi-stage, layer caching)
- [ ] Verify WSGI/ASGI server configuration (gunicorn workers, uvicorn settings)
- [ ] Find missing health check endpoints
- [ ] Check for proper signal handling (`SIGTERM`, `SIGINT`) for graceful shutdown
- [ ] Identify missing process manager configuration (supervisor, systemd)
- [ ] Verify database migration is part of deployment pipeline
- [ ] Check for proper static file serving configuration
- [ ] Find missing monitoring/observability setup (metrics, tracing, structured logging)
---
## 13. PYTHON VERSION & COMPATIBILITY
### 13.1 Deprecation & Migration
- [ ] Find `typing.Dict`, `typing.List`, `typing.Tuple` (use `dict`, `list`, `tuple` from 3.9+)
- [ ] Identify `typing.Optional[X]` that could be `X | None` (3.10+)
- [ ] Detect `typing.Union[X, Y]` that could be `X | Y` (3.10+)
- [ ] Find `@abstractmethod` without `ABC` base class
- [ ] Identify removed functions/modules for target Python version
- [ ] Check for `asyncio.get_event_loop()` deprecation (3.10+)
- [ ] Find `importlib.resources` usage compatible with target version
- [ ] Detect `match/case` usage if supporting <3.10
- [ ] Identify `ExceptionGroup` usage if supporting <3.11
- [ ] Check for `tomllib` usage if supporting <3.11
### 13.2 Future-Proofing
- [ ] Find code that will break with future Python versions
- [ ] Identify pending deprecation warnings
- [ ] Check for `__future__` imports that should be added
- [ ] Detect patterns that will be obsoleted by upcoming PEPs
- [ ] Identify `pkg_resources` usage (deprecated — use `importlib.metadata`)
- [ ] Find `distutils` usage (removed in 3.12)
---
## 14. EDGE CASES CHECKLIST
### 14.1 Input Edge Cases
- [ ] Empty strings, lists, dicts, sets
- [ ] Very large numbers (arbitrary precision in Python, but memory limits)
- [ ] Negative numbers where positive expected
- [ ] Zero values (division, indexing, slicing)
- [ ] `float('nan')`, `float('inf')`, `-float('inf')`
- [ ] Unicode characters, emoji, zero-width characters in string processing
- [ ] Very long strings (memory exhaustion)
- [ ] Deeply nested data structures (recursion limit: `sys.getrecursionlimit()`)
- [ ] `bytes` vs `str` confusion (especially in Python 3)
- [ ] Dictionary with unhashable keys (runtime TypeError)
### 14.2 Timing Edge Cases
- [ ] Leap years, DST transitions (`pytz` vs `zoneinfo` handling)
- [ ] Timezone-naive vs timezone-aware datetime mixing
- [ ] `datetime.utcnow()` deprecated in 3.12 (use `datetime.now(UTC)`)
- [ ] `time.time()` precision differences across platforms
- [ ] `timedelta` overflow with very large values
- [ ] Calendar edge cases (February 29, month boundaries)
- [ ] `dateutil.parser.parse()` ambiguous date formats
### 14.3 Platform Edge Cases
- [ ] File path handling across OS (`pathlib.Path` vs raw strings)
- [ ] Line ending differences (`\n` vs `\r\n`)
- [ ] File system case sensitivity differences
- [ ] Maximum path length constraints (Windows 260 chars)
- [ ] Locale-dependent string operations (`str.lower()` with Turkish locale)
- [ ] Process/thread limits on different platforms
- [ ] Signal handling differences (Windows vs Unix)
---
## OUTPUT FORMAT
For each issue found, provide:
### [SEVERITY: CRITICAL/HIGH/MEDIUM/LOW] Issue Title
**Category**: [Type Safety/Security/Performance/Concurrency/etc.]
**File**: path/to/file.py
**Line**: 123-145
**Impact**: Description of what could go wrong
**Current Code**:
```python
# problematic code
```
**Problem**: Detailed explanation of why this is an issue
**Recommendation**:
```python
# fixed code
```
**References**: Links to PEPs, documentation, CVEs, best practices
---
## PRIORITY MATRIX
1. **CRITICAL** (Fix Immediately):
- Security vulnerabilities (injection, `eval`, `pickle` on untrusted data)
- Data loss / corruption risks
- `eval()` / `exec()` with user input
- Hardcoded secrets in source code
2. **HIGH** (Fix This Sprint):
- Mutable default arguments
- Bare `except:` clauses
- Missing `await` on coroutines
- Resource leaks (unclosed files, connections)
- Race conditions in threaded code
3. **MEDIUM** (Fix Soon):
- Missing type hints on public APIs
- Code quality / idiom violations
- Test coverage gaps
- Performance issues in non-hot paths
4. **LOW** (Tech Debt):
- Style inconsistencies
- Minor optimizations
- Documentation gaps
- Naming improvements
---
## STATIC ANALYSIS TOOLS TO RUN
Before manual review, run these tools and include findings:
```bash
# Type checking (strict mode)
mypy --strict .
# or
pyright --pythonversion 3.12 .
# Linting (comprehensive)
ruff check --select ALL .
# or
flake8 --max-complexity 10 .
pylint --enable=all .
# Security scanning
bandit -r . -ll
pip-audit
safety check
# Dead code detection
vulture .
# Complexity analysis
radon cc . -a -nc
radon mi . -nc
# Import analysis
importlint .
# or check circular imports:
pydeps --noshow --cluster .
# Dependency analysis
pipdeptree --warn silence
deptry .
# Test coverage
pytest --cov=. --cov-report=term-missing --cov-fail-under=80
# Format check
ruff format --check .
# or
black --check .
# Type coverage
mypy --html-report typecoverage .
```
---
## FINAL SUMMARY
After completing the review, provide:
1. **Executive Summary**: 2-3 paragraphs overview
2. **Risk Assessment**: Overall risk level with justification
3. **Top 10 Critical Issues**: Prioritized list
4. **Recommended Action Plan**: Phased approach to fixes
5. **Estimated Effort**: Time estimates for remediation
6. **Metrics**:
- Total issues found by severity
- Code health score (1-10)
- Security score (1-10)
- Type safety score (1-10)
- Maintainability score (1-10)
- Test coverage percentage
Create Infographics
explain the thinking fast and slow book
{
"style": {
"name": "Whiteboard Infographic",
"description": "Hand-illustrated educational infographic with a warm, approachable sketch aesthetic. Upload your content outline and receive a visually organized, sketchbook-style guide that feels hand-crafted yet professionally structured."
},
"visual_foundation": {
"surface": {
"base": "Off-white to warm cream background",
"texture": "Subtle paper grain—not sterile, not digital",
"edges": "Content extends fully to edges, no border or frame, seamless finish",
"feel": "Like looking directly at a well-organized notebook page"
},
"overall_impression": "Approachable expertise—complex information made friendly through hand-drawn warmth"
},
"illustration_style": {
"line_quality": {
"type": "Hand-drawn ink sketch aesthetic",
"weight": "Medium strokes for main elements, thinner for details",
"character": "Confident but imperfect—slight wobble that proves human touch",
"edges": "Soft, not vector-crisp, occasional line overlap at corners",
"fills": "Loose hatching, gentle cross-hatching for shadows, never solid machine fills"
},
"icon_treatment": {
"style": "Simple, charming, slightly naive illustration",
"complexity": "Reduced to essential forms—readable at small sizes",
"personality": "Friendly and approachable, never corporate or sterile",
"consistency": "Same hand appears to have drawn everything"
},
"human_figures": {
"style": "Simple friendly characters, not anatomically detailed",
"faces": "Minimal features—dots for eyes, simple expressions",
"poses": "Clear, action-oriented, communicative gestures",
"diversity": "Varied silhouettes and suggestions of different people"
},
"objects_and_scenes": {
"approach": "Recognizable simplified sketches",
"detail_level": "Just enough to identify—laptop, phone, building, person",
"perspective": "Casual isometric or flat, not strict technical drawing",
"charm": "Slight imperfections add authenticity"
}
},
"color_philosophy": {
"palette_character": {
"mood": "Warm, optimistic, energetic but not overwhelming",
"saturation": "Medium—vibrant enough to guide the eye, soft enough to feel hand-colored",
"harmony": "Complementary and analogous combinations that feel intentional"
},
"primary_palette": {
"yellows": "Warm golden yellow, soft mustard—for highlights, backgrounds, energy",
"greens": "Fresh leaf green, soft teal—for success, growth, nature, money themes",
"blues": "Calm sky blue, soft navy—for trust, technology, stability",
"oranges": "Warm coral, soft peach—for warmth, calls-to-action, friendly alerts"
},
"supporting_palette": {
"neutrals": "Warm grays, soft browns, cream—never cold or stark",
"blacks": "Soft charcoal for lines, never pure #000000",
"whites": "Cream and off-white, paper-toned"
},
"color_application": {
"fills": "Watercolor-like washes, slightly uneven, transparent layers",
"backgrounds": "Soft color blocks to section content, gentle rounded rectangles",
"accents": "Strategic pops of brighter color to guide hierarchy",
"technique": "Colors may slightly escape line boundaries—hand-colored feel"
}
},
"typography_integration": {
"headline_style": {
"appearance": "Bold hand-lettered feel, slightly uneven baseline",
"weight": "Heavy, confident, attention-grabbing",
"case": "Often uppercase for major headers",
"color": "Dark charcoal or strategic color for emphasis"
},
"subheadings": {
"appearance": "Medium weight, still hand-drawn character",
"decoration": "May include underlines, simple banners, or highlight boxes",
"hierarchy": "Clear size reduction from headlines"
},
"body_text": {
"appearance": "Clean but warm, readable at smaller sizes",
"style": "Sans-serif with hand-written personality, or actual handwriting font",
"spacing": "Generous, never cramped"
},
"annotations": {
"style": "Casual handwritten notes, arrows pointing to elements",
"purpose": "Add explanation, emphasis, or personality",
"placement": "Organic, as if added while explaining"
}
},
"layout_architecture": {
"canvas": {
"framing": "NO BORDER, NO FRAME, NO EDGE DECORATION",
"boundary": "Content uses full canvas—elements may touch or bleed to edges",
"containment": "The infographic IS the image, not an image of an infographic"
},
"structure": {
"type": "Modular grid with organic flexibility",
"sections": "Clear numbered or lettered divisions",
"flow": "Left-to-right, top-to-bottom with visual hierarchy guiding the eye",
"breathing_room": "Generous white space preventing overwhelm"
},
"section_treatment": {
"borders": "Soft rounded rectangles, hand-drawn boxes, or color-blocked backgrounds",
"separation": "Clear but not rigid—sections feel connected yet distinct",
"numbering": "Circled numbers, badges, or playful indicators"
},
"visual_flow_devices": {
"arrows": "Hand-drawn, slightly curved, friendly pointers",
"connectors": "Dotted lines, simple paths showing relationships",
"progression": "Before/after layouts, step sequences, transformation arrows"
}
},
"information_hierarchy": {
"levels": {
"primary": "Large bold headers, bright color accents, main illustrations",
"secondary": "Subheadings, key icons, section backgrounds",
"tertiary": "Body text, supporting details, annotations",
"ambient": "Texture, subtle decorations, background elements"
},
"emphasis_techniques": {
"color_highlights": "Yellow marker-style highlighting behind key words",
"size_contrast": "Significant scale difference between hierarchy levels",
"boxing": "Important items in rounded rectangles or badge shapes",
"icons": "Checkmarks, stars, exclamation points for emphasis"
}
},
"decorative_elements": {
"badges_and_labels": {
"style": "Ribbon banners, circular badges, tag shapes",
"use": "Section labels, key terms, calls-to-action",
"character": "Hand-drawn, slightly imperfect, charming"
},
"connective_tissue": {
"arrows": "Curved, hand-drawn, with various head styles",
"lines": "Dotted paths, simple dividers, underlines",
"brackets": "Curly braces grouping related items"
},
"ambient_details": {
"small_icons": "Stars, checkmarks, bullets, sparkles",
"doodles": "Tiny relevant sketches filling awkward spaces",
"texture": "Subtle paper grain throughout"
}
},
"authenticity_markers": {
"hand_made_quality": {
"line_variation": "Natural thickness changes as if drawn with real pen pressure",
"color_bleeds": "Slight overflow past lines, watercolor-style edges",
"alignment": "Intentionally imperfect—text and elements slightly off-grid",
"overlap": "Elements may slightly overlap, creating depth and energy"
},
"material_honesty": {
"paper_feel": "Warm off-white with subtle texture",
"ink_quality": "Soft charcoal blacks, never harsh",
"marker_fills": "Slightly streaky, transparent layers visible"
},
"human_evidence": {
"corrections": "Occasional visible rework adds authenticity",
"spontaneity": "Some elements feel added as afterthoughts—annotations, small arrows",
"personality": "The whole piece feels like one person's visual thinking"
}
},
"technical_quality": {
"resolution": "High-resolution output suitable for print and digital",
"clarity": "All text readable, all icons recognizable",
"balance": "Visual weight distributed evenly across the composition",
"completeness": "Feels finished but not overworked—confident stopping point"
},
"enhancements_beyond_reference": {
"depth_additions": {
"subtle_shadows": "Soft drop shadows under section boxes for lift",
"layering": "Overlapping elements creating visual depth",
"dimension": "Slight 3D feel on badges and key elements"
},
"polish_improvements": {
"color_harmony": "More intentional palette relationships",
"spacing_rhythm": "Consistent margins and gutters",
"hierarchy_clarity": "Stronger differentiation between content levels"
},
"engagement_boosters": {
"focal_points": "Clear visual anchors drawing the eye",
"progression": "Satisfying visual journey through the content",
"reward_details": "Small delightful discoveries upon closer inspection"
}
},
"avoid": [
"ANY frame, border, or edge decoration around the infographic",
"Wooden frame or whiteboard frame effect",
"Drop shadow around the entire image as if it's a photo of something",
"The image looking like a photograph of a poster—it IS the poster",
"Sterile vector perfection—this should feel hand-made",
"Cold pure whites or harsh blacks",
"Rigid mechanical grid alignment",
"Corporate clip-art aesthetic",
"Overwhelming detail density—let it breathe",
"Clashing neon or garish color combinations",
"Uniform line weights throughout",
"Perfectly even color fills",
"Stiff, lifeless human figures",
"Digital sharpness that kills the warmth",
"Inconsistent illustration styles within the piece",
"Text-heavy sections without visual relief"
]
}