---
title: "Refining Specifications and Code"
description: "Guide for handling requirement changes at different stages of the SDD workflow."
type: skill
canonical_url: https://claudary.paisolsolutions.com/skills/refine
source: "Claudary"
difficulty: intermediate
author: "Claude Code Knowledge Pack"
date: 2026-07-10T11:37:32.770Z
license: CC-BY-4.0
attribution: "Refining Specifications and Code — Claudary (https://claudary.paisolsolutions.com/skills/refine)"
---

# Refining Specifications and Code
Guide for handling requirement changes at different stages of the SDD workflow.

## Overview

# Refining Specifications and Code

Guide for handling requirement changes at different stages of the SDD workflow.

## During Planning

When the specification needs adjustment after `/plan-task` completes:

### Option A: Pass the change directly

```bash
/plan-task --refine <requirement change>
```

The agent incorporates your change and re-runs affected stages.

**Examples:**

```bash
# Change authentication strategy
/plan-task --refine Use session-based auth instead of JWT

# Add a constraint the agent missed
/plan-task --refine The API must support pagination with cursor-based navigation, not offset

# Narrow the scope
/plan-task --refine Remove the admin dashboard from this task, we will handle it separately
```

### Option B: Edit the spec, then refine

1. Edit the task file in `.specs/tasks/todo/`
2. Add `//` comments to lines that need clarification
3. Run `/plan-task --refine`

The agent detects your edits, identifies the earliest modified section, and re-runs all stages from that point onward. Earlier sections remain unchanged.

**Example:** The agent planned a REST API, but you need GraphQL. Open the task file and edit:

```markdown
## Architecture Overview

// Change this to use GraphQL with Apollo Server instead of REST
- REST API with Express routes for CRUD operations
- PostgreSQL with Prisma ORM
```

Then run `/plan-task --refine`. The agent re-runs from architecture synthesis onward, producing new implementation steps for GraphQL while preserving the research and business analysis stages.

### What `--refine` compares

By default, `--refine` diffs local (unstaged) changes against staged changes. Both `/plan-task` and `/implement-task` stage their output at the end, so any manual edits you make afterward appear as unstaged changes.

To compare against the last commit instead, specify it: `/plan-task --refine compare with last commit`.

## After Implementation

When requirements change after `/implement-task` completes, choose based on the scope of the change:

### Small code adjustments

Edit the code directly, then run:

```bash
/implement-task --refine
```

The agent detects your changes, maps them to implementation steps, and aligns the rest of the codebase. If the judge passes your fix, it is accepted as-is. If it fails, the agent adjusts surrounding code to match your intent.

**Examples:**

```bash
# You fixed a validation bug in the controller — agent updates related tests and error messages
vi src/controllers/users.ts
/implement --refine

# You replaced bcrypt with argon2 in the auth service — agent aligns password checks elsewhere
vi src/services/auth.ts
/implement --refine

# You changed the database column name from `userName` to `username` — agent propagates across migrations, models, and queries
vi src/models/user.ts
/implement --refine
```

### Minor tweaks and polish

If the implementation is done and you need small refinements — renaming, formatting, minor behavior changes — run `/clear` (or re-open Claude Code) and work with agent as usual. No need to re-enter the SDD workflow.

**Examples:**

- Adjusting log messages or error text
- Renaming a local variable for clarity
- Tweaking CSS spacing or colors
- Adding a missing `console.log` for debugging

### Major requirement changes

If requirements changed substantially, create a new task:

```bash
/sdd:add-task "Refactor authentication implementation"
/plan-task
# /clear (or re-open Claude Code)
/implement-task
```

Re-running `/implement-task --refine` on large changes is less reliable than a fresh planning cycle. A new task produces a clean specification, proper architecture analysis, and accurate implementation steps.

**Examples of changes that warrant a new task:**

- Switching from a monolith to microservices
- Replacing the database engine (e.g., PostgreSQL to MongoDB)
- Changing the authentication model from API keys to OAuth2 with SSO
- Adding a real-time collaboration feature that was never in scope

## Walkthrough: Iterating on an Authentication Feature

A realistic sequence showing how refinement fits into the workflow:

```bash
# 1. Create and plan the task
/sdd:add-task "Add JWT authentication middleware"
/plan-task

# 2. Review the spec — agent chose HS256, but you need RS256
/plan-task --refine Use RS256 with rotating key pairs instead of HS256

# 3. Clear context, then implement
/clear
/implement-task

# 4. Review the code — token expiry is 1 hour, you want 15 minutes
vi src/config/auth.ts   # change TOKEN_EXPIRY to 900
/implement-task --refine     # agent updates tests and documentation to match

# 5. Product feedback: "Add refresh tokens"
# This is a significant scope addition — create a new task
/sdd:add-task "Add refresh token rotation for JWT auth"
/plan-task
/clear
/implement-task
```

---

Source: [Claudary](https://claudary.paisolsolutions.com/skills/refine) · https://claudary.paisolsolutions.com