Making a change

The commands for the person changing the site — start, edit, look at it, check it, submit.

About five minutes, start to pull request

Type these inside the project folder, one at a time. Claude replies in whatever language you write in — Japanese or English.

The five you will use every time

`/kaeru:start` — somewhere safe to work

Fetches the latest version of the site and opens a fresh workspace for your change. Nothing you do after this touches the live site until a developer agrees to it.

> /kaeru:start

  Got the latest version of the site.
  You're working on: "change the homepage heading"

  Go ahead — tell me what to change with /kaeru:edit-text

`/kaeru:edit-text` — say what to change

Describe it the way you would to a person. You never need a file name.

> /kaeru:edit-text
> change the homepage heading to "Welcome to Kaeru"

  Found the homepage heading in the Japanese and English text files.

  Before:  ようこそ
  After:   Welcome to Kaeru

  Changed in both languages. Look at it with /kaeru:preview

The homepage, as it is on the live site:

  ┌────────────────────────────────┐
  │                                │
  │   ようこそ                      │
  │   はじめましょう                 │
  │                                │
  └────────────────────────────────┘

There are two more like it: /kaeru:edit-image swaps a picture for one you point at, and /kaeru:edit-color changes a colour. Colours change by name — the site's own brand colour, everywhere it is used — rather than one button at a time, so nothing drifts out of step.

`/kaeru:preview` — look at it

Starts the site on your own computer, opens the page and shows you a picture of it. This is the point where you find out you meant something slightly different.

> /kaeru:preview

  Started the site at http://localhost:3000
  Opening the homepage…

  [screenshot]

  Does that look right?

`/kaeru:check` — catch your own mistakes

The one that saves the developer's time — and yours. It runs the project's tests, then looks at the page in a real browser, clicks what you changed, and asks the questions a reviewer would.

> /kaeru:check

  Before you submit

    Tests and lint ................ ✅ 3 passed
    Browser console ............... ⚠️  2 hydration warnings on /pricing
    Clicked what changed .......... ✅ the sign-in link opens /sign-in
    If it fails ................... ✅ doesn't apply — text only
    Runs on every request ......... ✅ doesn't apply — text only
    Not sure about ................ whether "Welcome" should be capitalised

  ⚠️ means worth a look before you submit, not that you did something wrong.

  Want me to fix the warnings? /kaeru:fix

Before you submit explains what each line means and why it exists.

`/kaeru:submit` — send it for review

Opens a pull request for the developer. It runs the checks again first and stops if something is unresolved, so nothing reaches review by accident. It never merges.

> /kaeru:submit

  Checks passed. Opening a pull request…

  ✅ Sent for review
  https://github.com/acme/site/pull/48

  The developer will review it. The preview link appears as a comment
  on that page in a minute or two.

The pull request is written for a person, not an engineer: what changed in one sentence, the page to look at, before and after side by side, anything you said you were unsure about, and the technical details folded away for the developer.

When something goes wrong

Command	Use it when
`/kaeru:status`	"Where has my change got to?" — checks, review, conflicts, in plain words
`/kaeru:fix`	A check went red. Fixes the simple, safe ones; hands the rest to the developer
`/kaeru:undo`	Go back a step, safely
`/kaeru:resolve`	Your change clashes with someone else's. Resolves the safe ones, escalates the rest
`/kaeru:help`	Anything confusing. Explains it gently and writes a note for the developer
`/kaeru:switch`	Pick up something else you were part-way through

> /kaeru:status

  Your change: "change the homepage heading"

  Tests ....... ✅ passed
  Review ...... ⏳ waiting for the developer
  Conflicts ... ✅ none

  Nothing to do — they'll look at it and let you know.

Two more worth knowing

/kaeru:check-a11y looks at whether the change is usable by everyone — readable colour contrast, images that describe themselves, links that make sense on their own. Worth running after a colour or image change.

/kaeru:learn is a guided practice run. It walks you through the whole flow on a real change so your first proper one is not also your first time.

The rules it works by

It never merges anything, and never pushes to the main branch.
/kaeru:fix only touches simple, safe things — formatting, typos, wording. A real error stops and goes to the developer instead of being guessed at.
Colours change by token, not by hand-editing a value somewhere.
Every change becomes a pull request somebody else has to agree with.

On this page