cupertino-repair
Use when something that already exists must be changed without breaking it -- fix, repair, adjust, extend, add to, or delete part of an existing dashboard, page, UI, CLI, library, build, kernel or platform. Trigger on 'fix this dashboard', 'this layout is broken on mobile', 'repair this', 'make X work again', 'remove this dead code', 'add a filter to this existing page', 'change this without breaking anything'. Runs objective -> baseline -> approved changeset -> scoped apply -> verify, with a hook that limits every edit to the approved item and a script-only, restorable delete. Not for designing something new: use cupertino-backwards then cupertino-council. Not for a full lifecycle pass: use cupertino-review.
- License 许可
- MIT
- 最近更新
- 2026-11-02
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- cupertino-repair
- description
- Use when something that already exists must be changed without breaking it -- fix, repair, adjust, extend, add to, or delete part of an existing dashboard, page, UI, CLI, library, build, kernel or platform. Trigger on 'fix this dashboard', 'this layout is broken on mobile', 'repair this', 'make X work again', 'remove this dead code', 'add a filter to this existing page', 'change this without breaking anything'. Runs objective -> baseline -> approved changeset -> scoped apply -> verify, with a hook that limits every edit to the approved item and a script-only, restorable delete. Not for designing something new: use cupertino-backwards then cupertino-council. Not for a full lifecycle pass: use cupertino-review.
02 资源文件 1
- 参考文档references/design-sources.md4.0 KB
03 SKILL.md 正文
cupertino-repair
Change an existing system so that exactly what was asked changes, and nothing else does. The other cupertino skills design something new; this one is for the opposite job, and it is the job they used to be misused for -- "fix my dashboard" routed into a redesign that fixed one thing and broke three.
Six operations, one route, any domain: read, verify, modify, add, create, delete. What differs between a dashboard and a kernel is only the probe that observes it (a rendered page, a command, a file), never the discipline.
The PreToolUse hook enforces the route while a run is active: no source edit before an
objective and a baseline exist; none before the changeset is approved; each edit only to
the paths of the one active item; no rm, mv, sed -i or shell redirect into a file;
no commit until a verdict exists; nothing under .cupertino/repair/ but the active run's
objective.json (until the baseline) and changeset.json is yours to write; and you may not
run repair_state.py approve -- approval is the user's. A denial is the route working -- read
its reason, do not route around it.
1. Preflight
python3 -B "${CLAUDE_PLUGIN_ROOT}/scripts/preflight_repair.py" --target <path the request is about>
Starts the run and prints what the target is (kind), which probes can run here, test and
build commands it found, design sources (matrize tokens, CSS custom properties with their
dark-mode blocks, chart libraries whose colours live in JS), whether the tree is clean, and a
verdict of ready or ready-with-gaps with each gap named. Tell the user every gap. A web
target with no browser driver can still be changed, but its checks will be reported "not
run", and a run with any "not run" check is never done.
2. Objective -- ask, never infer
Write .cupertino/repair/<run>/objective.json from what the user said, then show it and ask
them to confirm or correct it before going further. Ask when anything is unclear; do not
invent acceptance criteria the user did not state.
{
"objective": "On a 390 px phone the four KPI tiles overflow sideways; make them fit, and remove legacy-chart.js which nothing uses.",
"scope": ["dashboard/**"],
"nonGoals": ["no redesign of the tiles, sidebar or chart", "no colour changes"],
"acceptance": [
{"id": "A1", "criterion": "KPI row fits a 390 px viewport",
"check": {"kind": "web", "page": "dashboard/index.html", "width": 390, "scheme": "light",
"assert": {"noHorizontalOverflow": true, "noConsoleErrors": true}}},
{"id": "A2", "criterion": "legacy-chart.js is gone",
"check": {"kind": "file", "path": "dashboard/legacy-chart.js", "exists": false}}
],
"mustPreserve": [
{"id": "P1", "criterion": "desktop dark mode looks the same",
"check": {"kind": "web", "page": "dashboard/index.html", "width": 1280, "scheme": "dark",
"assert": {"maxPixelDiff": 0.5, "noConsoleErrors": true}}},
{"id": "P2", "criterion": "the test suite still passes",
"check": {"kind": "command", "run": "npm test", "assert": {"exit": 0}}}
]
}
mustPreserve is where "do not break it" becomes checkable. Propose at least one per thing the
user would be upset to lose -- the other theme, the other breakpoints, the test suite, the build,
a page that shares the stylesheet -- and let the user strike any. For a non-web target the same
shape holds: a CLI's acceptance is a command probe on its output; a kernel's is a boot script
that greps the console ("run": "make && ./scripts/boot-qemu.sh | grep -q 'login:'").
python3 -B "${CLAUDE_PLUGIN_ROOT}/scripts/repair_state.py" objective
It refuses a vague objective, an empty scope, or no acceptance criterion.
3. Read -- baseline before any edit
python3 -B "${CLAUDE_PLUGIN_ROOT}/scripts/baseline.py"
Runs every check as things are now and hashes every file in scope. Read the target too: its existing design system (CSS variables, the chart library and where its palette lives, component boundaries), its tests, and whatever the objective touches. If the user named a design source, read it now -- see design-sources.md for a Claude Design System artifact, matrize tokens, or the repo's own CSS. The existing system is the design system: a repair matches what is there unless the objective says otherwise.
An acceptance check that already passes at baseline means the objective is already met or the check is wrong -- say so before planning anything.
4. Plan -- the changeset
Write .cupertino/repair/<run>/changeset.json: one item per change, each the smallest change
that serves one acceptance criterion.
{"items": [
{"id": "I1", "op": "modify", "paths": ["dashboard/styles.css"],
"rationale": "let the KPI row wrap; tile size untouched so desktop is identical",
"preserves": ["P1"], "checks": ["A1"]},
{"id": "I2", "op": "delete", "paths": ["dashboard/legacy-chart.js"],
"rationale": "superseded in March", "evidence": "no file in dashboard/ loads it (grep)",
"checks": ["A2"]}
]}
| op | means | how it is applied |
|---|---|---|
read / verify |
inspect or run a check; changes nothing | nothing to apply |
modify |
change an existing file | Write/Edit, only its paths, file must exist |
add |
extend an existing file (new function, new section) | same as modify |
create |
a new file | Write, path must not exist yet |
delete |
remove a file | apply_delete.py only -- never rm |
Paths are concrete files inside scope, never globs. A delete carries evidence that nothing
depends on the file. Delete is a first-class repair, not something to avoid: dead code, a
superseded chart, a duplicated config are part of "fix it" when the user's objective covers them.
Show the changeset to the user as a table (id, op, paths, why) and ask them to approve it
themselves. The hook denies this command when you run it, because a model that can record
the user's approval can approve its own plan. Give the user the line to run, in their terminal
or in Claude Code with the ! prefix (a ! command runs directly, not as your tool call):
! python3 -B "${CLAUDE_PLUGIN_ROOT}/scripts/repair_state.py" approve
(An unattended run that was started with CUPERTINO_REPAIR_PREAPPROVED=1 in its environment -- the user's standing approval -- may run it directly.) Write the plugin path out in full when you show it -- ${CLAUDE_PLUGIN_ROOT} is not set in the
user's shell. Then wait; repair_state.py status shows approved once they have run it.
Approval is bound to the changeset's sha256: editing it afterwards voids the approval, and the
hook will deny every source edit until the user approves again.
5. Apply -- one item at a time
python3 -B "${CLAUDE_PLUGIN_ROOT}/scripts/repair_state.py" start-item I1
# Edit only the paths I1 names, with Write/Edit.
python3 -B "${CLAUDE_PLUGIN_ROOT}/scripts/repair_state.py" finish-item I1
python3 -B "${CLAUDE_PLUGIN_ROOT}/scripts/repair_state.py" start-item I2
python3 -B "${CLAUDE_PLUGIN_ROOT}/scripts/apply_delete.py" --item I2
python3 -B "${CLAUDE_PLUGIN_ROOT}/scripts/repair_state.py" finish-item I2
apply_delete.py searches the scope for anything still mentioning the file and refuses if it
finds something; show the user those lines and pass --accept-references only if they agree.
The file moves to trash/ with its hash, so apply_delete.py --restore can always put it back.
If an edit turns out to need a file no item names, stop. Add an item, re-show the changeset, approve again. Never widen scope silently -- that is the failure this skill exists to end.
Where a change touches colour in a chart drawn on canvas or SVG by JS, keep the literal or
resolve the variable in JS (getComputedStyle(document.documentElement).getPropertyValue('--x')).
ctx.fillStyle = "var(--accent)" paints black.
6. Verify
python3 -B "${CLAUDE_PLUGIN_ROOT}/scripts/verify.py"
Re-runs every check, compares each with its baseline, and attributes every changed file to the
approved item that allowed it. It writes verdict.json and .cupertino/repair/<run>/repair-report.html.
| verdict | meaning | next |
|---|---|---|
done |
every check passes, nothing "not run", every change attributed | show the report; repair_state.py end |
partial |
an acceptance check fails or could not run | plan the gap as a new item, approve, apply, verify again |
regressed |
a must-preserve check fails, a change has no item, or new console errors appeared | undo or fix the offending item first |
Three verdicts without done HALT the run ("halt": true). Do not try a fourth time. Offer the
user the two honest options: restore (apply_delete.py --restore, then
repair_state.py end --abandon and git checkout -- <changed paths>), or widen the objective
together. A repair that keeps retrying the same approach is guessing.
Always show the user, from the report: the verdict sentence, each check with its state and
detail, every change with its item, and every "not run" check under what this does not prove.
A done from a run where the browser probes could not run is not available -- verify.py will
say partial.
Output
cupertino-repair -- run 20261101T101500Z -- DONE (round 1)
objective: On a 390 px phone the four KPI tiles overflow sideways; make them fit ...
A1 KPI row fits a 390 px viewport pass scrollWidth 390 = clientWidth 390
A2 legacy-chart.js is gone pass
P1 desktop dark mode looks the same pass pixel difference 0.0%
P2 the test suite still passes pass exit 0
changes: dashboard/styles.css modified (I1) | dashboard/legacy-chart.js removed (I2, restorable)
not proven: rendering in browsers other than Chromium
report: .cupertino/repair/20261101T101500Z/repair-report.html
04 同仓库更多 Skills
toy-check
A skill that checks things in the repository and reports what it finds.
demo-check
Reports which generated files changed since the last generation run. Use when the user asks what drifted. Read-only; never edits a file.
demo-check
Reports which generated files changed since the last generation run. Use when the user asks what drifted. Read-only; never edits a file.
demo-check
Reports which generated files changed since the last generation run. Use when the user asks what drifted. Read-only; never edits a file.
demo-check
Reports which generated files changed since the last generation run. Use when the user asks what drifted. Read-only; never edits a file.
zirkel-verify-assumptions
Checks exactly ONE named assumption against real evidence in at most 3 steps and reports one outcome: confidence raised (>=90), reading changed, or still unresolved. Use to resolve a single load-bearing uncertainty — typically a blocking entry surfaced by zirkel-clarify-scope: "verify this one assumption", "is it actually true that X", "check this before we rely on it". For multiple uncertainties, invoke once per uncertainty — the step budget is never shared.