improve

Files (1)

• SKILL.md

SKILL.md (first lines)

# Improve

End-to-end workflow for **changing an existing feature**. The feature already works as specified; you want to extend or modify it. This skill keeps the **spec as the source of truth** (don't edit code without updating the spec) and **scales the ceremony to the size of the change**.

> **Routing:** new feature → `/feature` · change an existing feature → `/improve` (this skill) · bug you hit while testing → `/troubleshoot`.

This skill reuses the same building blocks as `/feature`:
- Your **spec layer** for the planning artifacts (amend the spec, plan, tasks)
- **Superpowers** for execution (`brainstorming`, `test-driven-development`, `subagent-driven-development`, `using-git-worktrees`, `finishing-a-development-branch`)
- The same two-stage review (spec-compliance + code-quality) on every change

## Stack profile (READ FIRST)

Load the project's **stack profile** before anything: `docs/stack.md` (preferred) or `sdd-stack.md` at repo root. If neither exists, prompt the user to create one from the plugin's `templates/sdd-stack.template.md`, or auto-detect conservative defaults. Everywhere this skill says **[PROJECT CONTEXT]**, substitute a compact summary from the profile (stack, binding files, conventions, frozen patterns, verify commands). Everywhere it says **[VERIFY]**, substitute the profile's *Verify commands*. Never hardcode a framework or build command.

See the profile's **Spec / planning layer** — adapt spec/plan/tasks steps to whatever spec tooling the project uses (Spec-Kit, plain markdown, or none). With no spec tooling configured, **default to plain-markdown specs**: for T2/T3 create a minimal `spec.md` if one doesn't exist, then amend it (create-then-amend). Don't require Spec-Kit.

## Input

`$ARGUMENTS` should contain a **feature reference** and a **change description**. Accept loose forms:
- `"leads-list — add a quality filter to the list header"`
- `"checkout: also show the tax breakdown per line item"`
- just a change description (no feature) — then resolve/ask for the feature (step 0).

## When to Use

- The feature exists and works to spec; you want to **add to it or change its behavior**.

**Don't use when:**
- It's brand-new functionality with no existing spec → `/feature`.
- The feature is producing a **wrong value / broken interaction / error** (it does NOT work as specified) → `/troubleshoot`. The line: *improve = change correct behavior; troubleshoot = fix incorrect behavior.* If unsure, ask the user.
- The feature works **exactly as built** but that built behavior is itself a **known defect or security hole** — that is *incorrect behavior* → `/troubleshoot`, even though nothing in the spec is changing. "Works as built" ≠ "works as specified" when the build was wrong.

## Scaling Guidance — decide before running

Match the ceremony to the change. Assess from `$ARGUMENTS` + a quick look at the resolved feature's spec and code surface:

| Tier | Size | Approach |
|------|------|----------|
| **T1 — Trivial** | < 30 min, 1–2 files, no user-visible behavior change (copy tweak, prop rename, small style fix) | Direct edit + verify. Update the spec only if the change alters documented behavior. Offer to do it inline. |
| **T2 — Scoped change** | 30 min – 2 hrs, single concern, localized | **Superpowers-only lane:** brainstorm (if vague) → branch/worktree → TDD (red→green) → two-stage review → finish/PR. Amend `spec.md` if behavior materially changes; skip plan/tasks regeneration. |
| **T3 — Substantial / behavioral** | > 2 hrs, multi-component, changes documented behavior or data shape, or user-shipped | **Full spec-amendment cycle:** amend spec → regenerate affected plan/tasks → worktree → per-task TDD loop with reviews → finish/PR. |

State the chosen tier to the user before proceeding. If T1, propose the inline path and stop unless they want more ceremony.

## Run mode — autonomous by default

Same contract as **`/feature` → "Run mode"** (see that skill for the full description). **Autonomous is the default** for **T2/T3** (T1 is a single direct edit, so the question doesn't arise): front-load the interactive gates, print the Decision Manifest, then run to PR stopping only at the stop-class. **Switch to step-through** only when the user asks to slow down ("run slowly", "stop at each step", "walk me through it"). Under `/loop` / no live user, run unattended.

- **Front-loaded block (main session):** grill (1b, if used) → amend spec → clarify (`/speckit-clarify`, interactive). For `/improve` the upfront decisions are about the **delta** — which fields/components change, migration/access-control impact, edge cases against existing behavior.
- **Decision Manifest** before going heads-down: resolved delta decisions + the deferred-decision policy.
- **Autonomous chain (subagents):** plan/tasks (T3) → analyze (3b) → worktree → implement loop → reviews → verify → finish.

**STOP-class (never guess; halt and surface even mid-run)** — identical to `/feature`: **schema / DB migrations** · **security / auth / secrets** · **frozen-pattern changes** · **one-way doors** (any hard-to-reverse choice with medium/significant refactoring or long-term maintenance cost — architecture, public API/contract shape, data model, framework/dependency choice, irreversible data ops; when unsure, treat as one-way and stop). `/improve` touches **working** code, so add one more reflex: **a change that would break backward compatibility** for existing callers/data is a one-way door — stop. Everything else (coverage gaps fixable by amending an artifact, convention-default ambiguities, MEDIUM/LOW analyze findings) is auto-resolve-and-log.

## Process Overview

```dot
digraph improve {
    rankdir=TB;
    "0. Resolve feature + read spec" [shape=box];
    "1. Assess change + pick tier" [shape=diamond];
    "T1: direct edit + verify" [shape=box];
    "1b. Grill design decisions" [shape=box];
    "2. Amend spec" [shape=box];
    "3. Regenerate plan/tasks (T3 only)" [shape=box];
    "3b. Analyze gate (T3, read-only)" [shape=box];
    "4. Worktree isolation" [shape=box];
    "5. Implement (TDD + 2-stage review)" [shape=box];
    "6. Verify (lint/build + suite)" [shape=box];
    "6b. Code-review gate (/code-review, T2/T3)" [shape=box];
    "7. Finish / PR" [shape=box];
    "DONE" [shape=doublecircle];

    "0. Resolve feature + read spec" -> "1. Assess change + pick tier";
    "1. Assess change + pick tier" -> "T1: direct edit + verify" [label="T1"];
    "T1: direct edit + verify" -> "DONE";
    "1. Assess change + pick tier" -> "1b. Grill design decisions" [label="T2 / T3"];
    "1b. Grill design decisions" -> "2. Amend spec";
    "2. Amend spec" -> "3. Regenerate plan/tasks (T3 only)";
    "3. Regenerate plan/tasks (T3 only)" -> "3b. Analyze gate (T3, read-only)";
    "3b. Analyze gate (T3, read-only)" -> "4. Worktree isolation";
    "4. Worktree isolation" -> "5. Implement (TDD + 2-stage review)";
    "5. Implement (TDD + 2-stage review)" -> "6. Verify (lint/build + suite)";
    "6. Verify (lint/build + suite)" -> "6b. Code-review gate (/code-review, T2/T3)";
    "6b. Code-review gate (/code-review, T2/T3)" -> "7. Finish / PR";
    "7. Finish / PR" -> "DONE";
}
```

## Step-by-Step Instructions

### 0. Resolve the feature + read its spec

1. Parse `$ARGUMENTS` into `FEATURE_HINT` and `CHANGE_DESCRIPTION`.
2. **Resolve the feature directory** using the profile's **spec location glob**. Search:
   ```
   <spec glob from profile, e.g. specs/**/spec.md>  | grep -i "<slug fragment from FEATURE_HINT>"
   ```
   - Exactly one match → that's `FEATURE_DIRECTORY`. Read its `spec.md` (and `plan.md`/`tasks.md` if present) — your **current-behavior baseline**.
   - Multiple or zero matches → ask the user which feature, listing candidates.
   - **No spec exists for the area** → this is effectively new work on undocumented code. Tell the user and offer to route to `/feature` (which will create a spec).
   - **No spec layer at all** (profile says "none") → read the impacted code directly as the baseline, AND create a minimal plain-markdown `spec.md` capturing the current + intended behavior before amending, so there's a contract to amend going forward. (Spec-Kit is not required — plain markdown is fine; default location `docs/specs/<NNN>-<slug>/`.)
3. Read the profile's **binding context files** and note any **frozen patterns** in the impacted area — changing those needs explicit user authorization.
4. Identify the code surface from the spec's impacted-files list + the change description.

### 1. Assess the change + pick a tier

Apply **Scaling Guidance**. State the tier and your reasoning. Also state the **run mode**: for T2/T3, **autonomous by default** (front-load grill+clarify, print the Decision Manifest, then run to PR stopping only at the stop-class); switch to **step-through** only if the user asked to slow down.

- **T1** → go to the T1 path, then stop.
- **T2 / T3** → continue to step 2.

**Brainstorm gate (conditional):** if the change is vague or has multiple plausible interpretations, invoke **`superpowers:brainstorming`** first.

**Grill gate (recommended for T3, optional for T2):** before amending the spec, invoke **`grill-me`** to stress-test the change's design decisions one branch at a time — each question carrying your recommended answer, exploring the existing code/spec to answer where possible. Resolves the design tree of the *delta* (which fields/components change, access-control impact, migration concerns if data shape changes, edge cases against existing behavior). Skip for T1, for an unambiguous small T2, or in any non-interactive context — record open decisions as NEEDS_CLARIFICATION instead.

---

From miroo93/dev-workflows, MIT.

More from miroo93/dev-workflows