Code Planning

A plan in the strict sense - [NEVER] write or edit code.

Planning is a three-phase pass: Analyze → Decide → Specify. The phases are ordered; the plan is complete only when all three have produced their part of the output, per the ## Output contract below.

Phase 1 - Analyze

Read the code to be touched before planning. Two analyses produce the analysis part of the plan.

Reuse analysis. Name what already exists that the plan reuses: existing functions, data shapes, patterns. This is the Code Manifesto's reuse-over-new-code rule and "Don't reinvent the wheel" from pablo-code-philosophy, applied as analysis, not as implementation. [ALWAYS] state what exists to reuse before proposing a new shape.

Abstraction analysis. Scan the code to be touched for abstraction candidates and report one signal line per category - no thresholds, no gates, no tables:

• A1 Missing or misplaced abstractions - same logic repeated, or a class or function carrying more than one reason to change.
• A2 Weak encapsulation - mutable state or invariants exposed, callers doing the validation the object should own.
• A3 Poor data types - primitives or null standing in for a domain type; exceptions used for expected control flow.
• A4 Flag/enum-modeled variants - a discriminator drives dispatch that a sealed ADT would express directly.

For a formal verdict on a candidate, load refactor-identification and read its references/examples.md for calibrated detection examples, then apply its full methodology (tables, thresholds, gates, and priorities).

Phase 2 - Decide

[ALWAYS] load pablo-code-philosophy before running this phase; the pipeline lives there and this skill does not restate it. Then run every abstraction and scope decision through the decision pipeline YAGNI → KISS → DRY → SOLID of pablo-code-philosophy and its conflict precedence KISS > DRY > SOLID. The pipeline, its gates, and the conflict matrix live there as the single source.

Phase 3 - Specify

Specify the contracts the plan commits to.

• Public API. Signatures of public functions and the shapes of their data. Start from the data model: "Data structures first" and "Thin entry points" from pablo-code-philosophy govern the shapes, and the testable boundary is the seam, per pablo-tdd.
• Test plan. Which tests, at which seams, which edge cases. The standards for a good test and seam confirmation live in pablo-tdd; the plan names seams and edge cases, it does not re-state the standards. The seams the plan lists are proposals: pablo-tdd requires confirming them with the user before tests are written.
• Verification criteria. Every step of the plan carries one, in the "[Step] → verify: [check]" format defined once in the ## Output contract below. For multi-step tasks, one verification line per step.

Ambiguity

The "Before Coding" section of pablo-code-philosophy governs this behavior: [DO NOT] pick silently among interpretations, state assumptions, name the confusion, ask.

Output

The plan is the deliverable: analysis, decisions, and contracts, and nothing else.

• Analysis - reuse opportunities and the A1-A4 signal lines.
• Decisions - pipeline verdicts, cited to pablo-code-philosophy by name.
• Contracts - public API signatures, data shapes, seams, test plan.
• Verification - every step with "[Step] → verify: [check]". This is the single definition of the verification format.

The four blocks are first-class output: [ALWAYS] deliver analysis and verification alongside decisions and contracts; do not drop them when converting to a consumer's format. The plan may be delivered as a single document or split per the consumer's contract (e.g. the planner agent's PLAN / TECHNICAL sections); whatever the format, [ALWAYS] preserve the per-step verification criteria.

Cross-references

Load methodology from its owner by name; never duplicate it.

• pablo-goal-discovery - upstream. This skill assumes a confirmed goal; if the objective isn't confirmed yet, run that skill first.
• pablo-code-philosophy - decision pipeline, conflict precedence, "Data structures first", "Thin entry points", the Code Manifesto's reuse rule, "Don't reinvent the wheel", "Before Coding".
• refactor-identification - the full A1-A4 methodology: tables, thresholds, gates, priorities, and worked examples in its references/examples.md.
• pablo-tdd - what a good test is, seams, test-plan standards.