ryanthedev/code-foundations/cc-pseudocode-programming

cc-pseudocode-programming

Design a routine in pseudocode before writing it. Iterating on intent is cheaper than iterating on code, and four questions catch the expensive mistakes early:

If the user asks to skip pseudocode, comply or surface the tradeoff once (the routine will likely cost more in debugging) — don't refuse.

When the routine is exempt

Skip the process only when one of these holds:

• Simple accessor — getValue()/setName() with no validation, transformation, or side effects.
• Pure pass-through — delegation with no parameter transformation or error wrapping.
• Trivial one-liner — all of: single statement, zero decision points, zero loops, implementation obvious from the signature alone.
• Already designed — a design document specifies the exact algorithm, error handling, and edge cases.

A routine you're debating as "trivial enough" is not trivial — design it.

Modes

APPLIER

Guide routine design with the Pseudocode Programming Process. Produces pseudocode design, header comments, and an implementation plan.

1. Confirm the routine's place in the overall design is clear.
2. Define the problem: inputs, outputs, preconditions, postconditions, what it hides.
3. Name the routine — if naming is hard, the design is unclear; iterate.
4. Plan how you'll test it before writing code.
5. Check libraries for existing functionality before building.
6. Plan error handling — think through failure modes.
7. Research relevant algorithms if needed.
8. Write pseudocode as a header comment in natural language (language-independent, intent not syntax).
9. Iterate until generating code from each line is nearly automatic — you can write each line without pausing to decide how. If you stop to think "how do I implement this part?", the pseudocode needs more detail.
10. Try alternatives; keep the best.
11. Code from the pseudocode, which becomes the comments.
12. Compile clean at the strictest warning level.

"Convinced it's correct" means you can mentally trace every path — happy, error, edge — and explain why each produces the right output. "It looks right" is not convinced.

Good vs bad pseudocode

Pseudocode at the level of intent, no target-language syntax:

If another resource is available
    Allocate a dialog box structure
    If a dialog box structure could be allocated
        Note that one more resource is in use
        Initialize the resource
        Store the resource number at the location provided by the caller
        Return success
    Endif
Endif
Return failure

This reads as English, becomes excellent comments, and is precise enough to generate code from. The anti-pattern instead writes *hRsrcPtr, malloc(), return 1 — target-language detail that focuses on HOW, exposes implementation, and makes poor comments.

CHECKER

Verify the produced pseudocode and resulting routine. Checklist: Read(${CLAUDE_SKILL_DIR}/checklists.md). Assess the artifacts:

• Is the pseudocode at the level of intent (English, not target-language syntax)?
• Is it detailed enough that code generation from it is nearly automatic?
• Does at least one alternative approach appear to have been weighed?
• Can the routine's correctness be explained by tracing all paths?
• Are all compiler warnings eliminated?