vertical-ordering

Organize Python function definitions to prioritize callers over helpers.

3|7|Updated Nov 7, 2025
One-click install
npx skills add https://github.com/dimagi/dimagi-claude-workflows --skill vertical-ordering
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: vertical-ordering
Source: https://github.com/dimagi/dimagi-claude-workflows/tree/main/plugins/dev_utils/skills/vertical-ordering
Command: npx skills add https://github.com/dimagi/dimagi-claude-workflows --skill vertical-ordering

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Improves code readability by organizing functions so that high-level callers appear before their helper implementations, making modules easier to scan and reason about during development and review.

Core Features & Use Cases

  • Caller-first ordering: Encourages placing public or high-level functions above the helpers they invoke.
  • Refactor guidance: Use when extracting helpers, reorganizing modules, or introducing new functions to maintain readable flow.
  • Call-chain preservation: Guides ordering for chains of calls and shared helper placement to reduce reader context switches.

Quick Start

Reorder the module so that high-level functions appear above their helper functions to make the file read top-down.

Frequently Asked Questions about vertical-ordering

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I organize Python functions to read top-down?

Organize Python functions by placing high-level callers first and helper implementations below them. This caller-first ordering makes modules easier to scan and reason about during development and code review.

What is vertical ordering in code refactoring?

Vertical ordering in code refactoring is the practice of structuring function definitions so public callers appear above their helpers. It preserves call chains and reduces reader context switches for improved readability.

When should I reorder functions during a module refactor?

Reorder functions during a module refactor when extracting helpers, writing new functions, or reorganizing code. Apply caller-first placement to maintain a readable flow and guide shared helper positioning.

What's the best way to order shared helpers with multiple callers?

The best way to order shared helpers with multiple callers is to place the high-level caller functions above the shared helper implementations. This guides placement and reduces the context switches needed to understand the code.

Can I use vertical ordering for typical Python projects?

Yes, you can use vertical ordering for typical Python projects. It applies during writing new functions, extracting helpers, refactoring modules, and reorganizing code to enforce caller-first ordering and preserve call chains.