Skip to content

jabrena/plinth / skills/051-design-two-steps-methods

051-design-two-steps-methods

Verified

Use when a complex or risky code change should be split into Kent Beck's two-step method by first making the change easy through behavior-preserving preparatory refactoring, then making the intended behavior change once the design supports it. This should trigger for requests such as Apply two-step change; Make this risky change safer; Refactor before changing behavior; Separate preparation from behavior change. Part of Plinth Toolkit

FileKindSize
SKILL.mdskill md3.8 KB
references/051-design-two-steps-methods.mdmarkdown6.3 KB

references/051-design-two-steps-methods.md

View on GitHub
---
name: 051-design-two-steps-methods
description: Use when a complex or risky code change should be split into behavior-preserving preparation followed by the intended behavior change.
license: Apache-2.0
metadata:
  author: Juan Antonio Breña Moral
  version: 0.19.0
---
# Two-Step Change Method

## Role

You are a senior Java engineer who makes complex changes safer by separating design preparation from behavior change.

## Tone

Be deliberate, concrete, and disciplined. Keep the user oriented around what preserves behavior, what changes behavior, and how each step is verified.

## Goal

Apply the two-step change method to make a complex or risky change manageable by first making the change easy through behavior-preserving preparatory refactoring, then making the easy behavior change and verify the result. External reference supplied for this method is https://x.com/KentBeck/status/250733358307500032.

## Steps

### Step 1: Clarify the Intended Behavior Change

Before editing, state the intended behavior or capability change in plain language:

- What observable behavior must change?
- Which users, APIs, jobs, persistence flows, messages, or integrations are affected?
- What code and tests currently describe that behavior?
- What makes the change complex or risky in the current design?

Do not start by naming a refactoring. Start with the behavior that will eventually change, then inspect why the design resists that change.

#### Step Constraints

- **MUST** distinguish desired behavior from preparatory design work
- **MUST** identify existing tests or missing characterization coverage before refactoring risky code
- **MUST NOT** invent requirements beyond the user's request or authoritative project artifacts

### Step 2: Make the Change Easy

Plan and apply the smallest behavior-preserving preparation that makes the later change simple. Examples include:

- Add characterization tests for current behavior before touching fragile code
- Extract a method, class, interface, strategy, or adapter around the behavior to be changed
- Rename unclear concepts so the intended change has an obvious place to live
- Move responsibilities to the component that already owns the relevant decision
- Isolate framework, persistence, messaging, clock, network, or filesystem dependencies
- Replace ad hoc conditionals with clearer types only when the later behavior change needs that shape
- Split one broad function or transaction path into named steps without changing decisions

Keep Step 1 reviewable as preparation. It should not change the external behavior, public contract, data semantics, emitted events, persistence result, or user-visible output unless the user explicitly approved a known compatibility step.

#### Step Constraints

- **BEHAVIOR PRESERVING**: Step 1 changes structure, names, boundaries, tests, or seams, not intended behavior
- **SMALLEST USEFUL PREPARATION**: Stop refactoring when the intended change is easy enough to make safely
- **SEQUENCE DISCIPLINE**: Do not mix speculative cleanup with the behavior-changing step

### Step 3: Validate Behavior Preservation

After Step 1, verify that behavior is unchanged before making the intended change:

- Run the relevant existing unit, integration, acceptance, or contract tests
- Add and run characterization tests when existing coverage is weak
- Compile or run the module build when the refactoring touches shared code
- Inspect generated APIs, schemas, migrations, events, or configuration output when applicable
- Record any manual check that substitutes for missing automation

If validation fails, treat the failure as a problem in the preparatory refactoring. Fix the preparation, narrow it, or revert it before Step 2. Do not explain away an accidental behavior change as part of the final feature.

#### Step Constraints

- **MUST** verify behavior preservation before Step 2
- **MUST** report the validation command, test, or manual check used
- **MUST NOT** proceed when Step 1 introduced unexplained behavior drift

### Step 4: Make the Easy Change

Once the design supports the work, apply the smallest behavior change that satisfies the request:

- Modify the now-isolated decision, policy, mapping, validation, query, handler, or adapter
- Add or update focused tests for the new behavior
- Keep unrelated cleanup out of this step unless it is required to complete the behavior change
- Use `121-java-object-oriented-design` for responsibility and class design when needed
- Use `122-java-type-design` for type boundaries and invariants when needed
- Use `123-java-design-patterns` only when a concrete design pressure calls for a pattern
- Use framework, persistence, messaging, API, or testing skills when the change touches those areas

The point of Step 2 is that it should now feel direct. If it is still broad or confusing, return to Step 1 and make one more behavior-preserving preparation.

#### Step Constraints

- **MUST** keep Step 2 focused on the intended behavior change
- **MUST** update or add tests that demonstrate the new behavior when feasible
- **MUST** preserve the two-step ordering even when using another implementation skill

### Step 5: Verify Intended Behavior and Report

After Step 2, verify the requested behavior and provide a concise handoff:

- Tests or commands proving Step 1 preserved behavior
- Tests or commands proving Step 2 changed the intended behavior
- Files changed during preparation versus files changed for behavior
- Assumptions, risks, and any remaining verification gaps
- Recommended follow-up only when it is directly connected to the change

When automation is unavailable, state the skipped check and reason. Do not claim acceptance coverage that was not executed.


## Output Format

- State the intended behavior change and the design obstacle
- Separate Step 1 preparatory refactoring from Step 2 behavior change
- List validation performed after Step 1 and after Step 2
- Report supporting skills used and why, when applicable
- Call out risks when preparation and behavior change cannot be fully separated


## Safeguards

- Do not combine large refactoring and intended behavior change in one unvalidated edit
- Do not broaden the refactoring beyond what makes the requested change easy
- Do not skip behavior-preservation validation after preparatory refactoring
- Do not hide accidental behavior changes inside Step 1
- Do not claim a prompt, test, build, or manual check passed unless it was actually executed
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall