shaping

name	shaping
description	Trigger: how do I approach X, cómo lo abordo, scope this, help me plan, por dónde empiezo. Bound the problem and recommend approach before writing code. Skip: execution tasks.
author	Gonzalo Astudillo
version	1.0.0
date	"2026-04-14T00:00:00.000Z"
user-invocable	true

Shaping — Design Before Implementation

The Iron Law

NO IMPLEMENTATION BEFORE ALIGNMENT.

Never write code until the problem is defined, options are evaluated, and a recommendation is chosen. Starting to code without alignment wastes everyone's time.

The Five Phases

Phase 1: Investigate

Silently read the codebase. Understand existing patterns, connections, and affected systems.

• Verify by running, not just reading — use throwaway scripts or grep
• Never assume runtime behavior

Phase 2: Problem

Define WHAT is needed as numbered requirements:

• Describe outcomes and constraints, never implementations
• Interview depth-first — one decision at a time
• Establish acceptance criteria as observable behavior

Phase 3: Options

Present 2–3 concrete approaches in a comparison table:

Criteria	Option A	Option B	Option C
Requirement 1	✅	✅	❌
Requirement 2	✅	❌	✅
Unknowns	—	⚠️	—

If all options pass but one feels wrong — there's a missing requirement. Find it.

Phase 4: Recommend

Present your recommendation with reasoning before waiting for choice. Do not proceed until the user decides.

Phase 5: Slice

Break work into vertical slices — each slice cuts through all layers (data + logic + UI). Never horizontal (all DB migrations, then all API, then all UI).

Every implementation ends with a Verification section describing observable behavior beyond passing tests.

Decision Gates

Situation	Action
Trivial task (1 file, obvious path)	Skip to Phase 4 — one sentence recommendation
Clear problem, unclear approach	Phases 2–4 only — skip full investigation
Ambiguous problem + complex system	Full 5-phase cycle
User gives options, asks which	Skip to Phase 4 — evaluate and recommend

Critical Rules

• One decision per message — depth-first, not breadth-first
• Challenge with evidence from the codebase, not assumptions
• Spike unknowns that would change your recommendation before presenting options
• Scale to task size: one sentence for trivial tasks, full doc for architectural changes

Output Contract

Return exactly 5 sections:

1. Problem — what needs to happen (outcomes, not implementation)
2. Constraints — things that cannot change
3. Options — comparison table with ✅/❌/⚠️ per requirement
4. Recommendation — chosen option with concrete first step
5. Verification — how to observe that the implementation succeeded

Gotchas

• Claude tends to jump to Options without completing Phase 1 investigation — always read the codebase first
• Phase 3 options often look too similar — force at least one option with a radically different trade-off
• "I'll implement it now" is not a recommendation — Phase 4 must state the specific first action