laurigates/design-pseudocode

Design by Pseudocode

From Code Complete (McConnell), the Pseudocode Programming Process: before writing a non-trivial routine, design it in pseudocode — intent-level English statements, one per step — refining top-down until each line is obvious to translate into code. You catch the hard cases, the wrong decomposition, and the missing error path while editing prose, which is an order of magnitude cheaper than catching them while editing code. The finished pseudocode then becomes the routine's comments, so the design survives as documentation.

This is a pre-implementation design technique: it decides a routine's internal structure, names its steps, and surfaces its edge cases before a single line of real code is committed.

When to Use This Skill

| Use this skill when... | Use something else instead when... | |---|---| | Designing a complex routine or non-trivial algorithm before coding | Verifying whole-project premises before a wave → agent-patterns-plugin:verify-before-plan | | The decomposition isn't obvious and you want to fail cheap in prose | Choosing a structural design pattern → software-design-plugin:design-patterns | | Naming steps + edge cases up front, then keeping them as comments | A multi-file refactor plan → workflow-orchestration-plugin:workflow-checkpoint-refactor | | Reviewing whether a stub's intended logic is sound before it's built | Reviewing already-written code → code-quality-plugin:code-review |

Core Principle

| Step | What you do | What it buys | |---|---|---| | 1. Intent | State the routine's contract: inputs, output, one-line job | A clear target before mechanism | | 2. Refine | Decompose into intent-level steps; refine each until trivial | The decomposition is judged in prose | | 3. Check edges | Walk error paths, empty/boundary inputs, failure modes | Missing cases found before code | | 4. Promote | Each pseudocode line becomes a comment; fill code beneath | Design survives as documentation |

Pseudocode is intent, not syntax: "find the first overdue invoice" — not for (i=0; i<n; i++). If a line is already code-shaped, it's too low; if you can't translate a line directly to a few statements, it's too high — refine it.

Parameters

Parse $ARGUMENTS:

• Target or description (optional) — a free-text description of the routine to design, or a stub file/diff whose intended logic to work out. If absent, default to the current change (git diff HEAD) and design the routine it stubs.

Execution

Execute this pseudocode design pass:

Step 1: State the contract

One line each: what the routine takes, what it returns/guarantees, and its single job. If it has more than one job, that's a decomposition signal — design the pieces separately (pairs well with software-design-plugin:design-by-contract).

Step 2: Refine top-down

Write the routine as a short list of intent-level steps. Refine any step that isn't obvious-to-code into sub-steps. Stop when every line maps to a few statements. Resist writing real syntax — the value is judging the shape before committing to it.

Step 3: Walk the edges

Against the pseudocode, walk: empty/null/boundary inputs, the failure of each external call, and the postcondition under each path. Add the handling as pseudocode lines. A case you can't place is a sign the decomposition is wrong — revise the steps, not just patch the end.

Step 4: Promote to comments and report

Emit the refined pseudocode as the routine's comment skeleton (each line a comment, code to be filled beneath). Report: the contract, the step decomposition, the edge cases surfaced, and any decomposition smell (a step doing two jobs, a missing error path) found during refinement.

Anti-patterns

| Mistake | Correct approach | |---|---| | Writing real code and calling it pseudocode | Intent-level English; if it's syntax, raise the altitude | | Pseudocode so vague a step hides a whole algorithm | If a line won't translate to a few statements, refine it | | Skipping the edge-case walk | Step 3 is where pseudocode pays for itself | | Throwing the pseudocode away after coding | Promote it to comments — the design becomes the docs |

Quick Reference

| Altitude check | Verdict | |---|---| | Line reads as for/if/while (...) | Too low — that's code | | Line maps to 1-5 statements of intent | Just right | | Line hides a whole sub-algorithm | Too high — refine it | | A step does two distinct jobs | Decompose into separate routines |

Related

• software-design-plugin:design-by-contract — Step 1's contract is the precondition/postcondition pair, made explicit
• software-design-plugin:design-patterns — when refinement reveals recurring variation, a pattern may be the right step structure
• code-quality-plugin:code-review — reviews the code after; this designs it before
• agent-patterns-plugin:verify-before-plan — the project-scale sibling: verify premises before a multi-agent plan, as this refines a routine before code