---
name: plan-change
description: Plan a substantial code change before implementing it. Grounds the request in the codebase, maps affected modules, contracts, consumers, data, and trust boundaries, assesses risk, and splits the work into small verifiable slices with acceptance criteria and a verification plan. Use when asked to plan, scope, design, or assess the impact of a change, before multi-module or high-risk work such as payments, authorization, migrations, integrations, or architectural changes.
title: plan-change
canonical_url: https://skilld.dev/gh/akdevsaha-dev/factory-skills/plan-change
last_updated: 2026-11-18T12:30:23.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> Supporting files, fetch one when the Skill refers to it: [references/architecture.md](https://skilld.dev/api/skills-raw/akdevsaha-dev/factory-skills/plan-change/references/architecture.md), [references/operating-rules.md](https://skilld.dev/api/skills-raw/akdevsaha-dev/factory-skills/plan-change/references/operating-rules.md), [references/security.md](https://skilld.dev/api/skills-raw/akdevsaha-dev/factory-skills/plan-change/references/security.md).
>
> If the user asked to install this Skill, run `npx skilld install akdevsaha-dev/factory-skills/plan-change`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/plan-change`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/akdevsaha-dev/factory-skills/plan-change) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/plan-change`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/plan-change --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/plan-change --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# Plan Change

Produce the smallest plan that lets the change be built correctly and verified: what changes, what it affects, how risky it is, and in what order to build it. A plan is a tool for the implementer, not a document to impress a reader.

Read `references/operating-rules.md` first, then `references/architecture.md`. Read `references/security.md` when the change crosses a trust boundary.

## Use when

- The change spans several modules, layers, or services
- It is high-risk by the tiers in `references/operating-rules.md`
- It changes a contract other code depends on
- The user asks for a plan or an impact assessment

For a small change in one place, skip planning; `implement-feature` plans inline.

## Inputs

- The request, or acceptance criteria if a caller already wrote them
- Optionally an impact map draft, the effort profile, and the files already read. Do not reread what the caller already summarized.

## Procedure

1. **Ground the request.** Find the code each term refers to. Turn the request into acceptance criteria: inputs, outputs, permissions, visible behavior, and failure behavior.
2. **Find the nearest analog**, and trace it end to end, as `references/architecture.md` describes. It decides layers, file placement, and test style.
3. **Map the impact.** Fill in every line of the impact map in `references/operating-rules.md` from real code. Find consumers by searching for the contract: route paths, exported names, schema fields, event names, env vars. Follow data flow from entry point to storage and back.
4. **Assess risk.** Assign the tier. For each high-risk area, name the invariants that must hold: amounts never exceed what was captured, each webhook is processed once, users only see their own tenant's data.
5. **Choose the design.** Prefer extending what exists. When there is a real choice, give the options in one line each and pick one with the reason. Do not add layers, abstractions, or configuration the task does not need.
6. **Slice the work.** Order slices so that each one leaves the system working and can be verified on its own, usually data, then core logic, then entry points, then consumers. Keep them few.
7. **Plan verification.** For each acceptance criterion and invariant, name the check that proves it: an existing test, a new test, an API call, or a browser flow. Name only checks the impact justifies. A tool the project lacks is not a reason to drop a check: `verify-work` can often run it without changing the project, such as a browser check through the Playwright CLI.

The effort profile sets depth: a few lines for `snack`, deeper architecture for `feast`, and failure modes and security boundaries for each slice for `banquet`.

## Output

```text
Goal          Partial and full refunds from the order page, settled by the provider webhook
Criteria      1. Owner or admin can refund up to the captured amount  2. Duplicate requests refund once
              3. Webhook marks the refund settled; unsigned webhooks are rejected  4. UI shows pending and errors
Analog        Capture flow: routes/payments.ts → PaymentService → PaymentRepository, webhooks/stripe.ts
Impact map    (every line from references/operating-rules.md)
Risk          High-risk: money movement, webhook trust boundary
Invariants    refunded_cents ≤ captured_cents; one refund per idempotency key; signature checked before parsing
Design        Store refunded_cents on payments (matches captured_cents); no new ledger table
Slices        1. Migration + repository  2. RefundService + provider call  3. POST /refunds + webhook  4. Refund dialog
Verification  Criterion 1: service tests + API 403/404 tests; 2: concurrent request test; 3: signed and unsigned
              webhook tests; 4: browser flow on the order page. Migration up/down on a disposable DB
Assumptions   Admins may refund any order (matches capture). Partial refunds only in the order currency
Questions     None
```

## Escalate

- Interpretations differ in ways that affect correctness, security, data, or architecture: ask, with options and a recommended default
- The design needs a new architectural pattern, a breaking contract change, or a destructive migration: state it and get approval

## Hand off

- High-risk plans go to the user for approval before any edit
- Approved plans go to `implement-feature`, slice by slice, or back to `hungry-jack` when it called this skill
- The verification plan goes to `verify-work`

Before you finish, check your list of available skills for each skill named in this section. If any is missing, end your report with the missing names, this command, and the question "Should I install them for you, or will you install them yourself?" Follow "Missing companion skills" in `references/operating-rules.md` for the rest.

```bash
npx skills add akdevsaha-dev/factory-skills --skill hungry-jack plan-change implement-feature verify-work simplify-code review-changes reflect
```

## Done when

Every acceptance criterion maps to a slice and to a check, every line of the impact map is filled from code, and the risk tier and its invariants are stated.
