Iteration

Iteration — land a change as a reviewed PR

The disciplined per-change loop, and the single source of truth for it:

> implement → simplify → commit → push → PR → considerations → test links

The chat summary is produced last, after the change is already pushed and in the PR. Never lead with the summary.

Two ways this runs

Detect the mode once, at the start:

• Feature context — you're inside a feature task worktree: there is a

//.feature.json for the checkout you're in, and the workspace has a .claude/feature/config.json. The feature skill invokes this contract here. Use the configured base branch per repo, span all involved repos, persist the dashboard artifacts, and hand out pretty URLs.

• Standalone — anything else (a plain repo/branch, you invoked me directly). Operate on the

current git repo, PR into its default base branch, and give plain how-to-verify instead of pretty URLs. No worktree, no servers, no dashboard bookkeeping.

Read the feature config (works in both modes — it just returns defaults with no repos when there's no workspace):

# ROOT = walk up from cwd to the dir holding .claude/feature/config.json; else the repo root
python3 "${CLAUDE_PLUGIN_ROOT}/skills/feature/scripts/config.py" --root "$ROOT"

_override_applied: true and a .feature.json beside your checkout ⇒ feature context. Otherwise standalone.

Guard (standalone): never commit straight onto a base/default branch. If git branch --show-current is the default branch, create a topic branch first (git switch -c ); then proceed. In feature context the worktree is already on its task- branch — just use it.

The contract — in order

Let WT = the checkout you work in: each involved repo's worktree in feature context, or the current repo in standalone. Run steps per involved repo.

1. Implement

Make the requested change(s) in WT only — never the main checkout or a base branch. Read every file before you Edit it (Edit/Write require a prior Read this session; editing unread files is the top error class). About to touch several files → Read them all first.

2. Simplify — MANDATORY after a significant change

Invoke the /simplify skill (a real Skill invocation, not a mention) scoped to the files you changed this iteration. It cleans reuse/duplication/dead code/readability, must not change behavior; its edits are part of this commit. (If /simplify isn't installed, do the equivalent manual pass and say so.)

Significant ⇒ required. Minor ⇒ may skip (the only allowed skip):

| Skip (minor) | Run (significant) | |---|---| | one-/few-line diff in 1 file, no new or restructured logic | adds or changes logic / control flow | | a constant, copy/string, type, import, config value, comment, version bump | a new function/component/hook/endpoint | | a pure revert | a refactor, or a change spanning multiple files |

When in doubt → run it. Then declare the outcome in the summary: simplify: ✓ or simplify: skipped (minor). Never omit it silently — a silent skip is a contract violation.

2b. Considerations — validate every applicable cross-cutting dimension

Read the config's considerations list — feature context: python3 "${CLAUDE_PLUGIN_ROOT}/skills/feature/scripts/config.py" --root "$ROOT" → .considerations (or read .claude/feature/config.json); standalone with no config ⇒ empty ⇒ skip this step silently. Each entry is a recurring blind spot — something features get specified without (desktop-only, LTR-only, Chrome-only) and that then ships broken. For each entry:

1. Decide applicability from its when (free-text condition) and optional repos (only applies

when one of those repos is touched this iteration). Backend-only diffs usually make UI dimensions n/a.

1. For every applicable entry, actually verify the change satisfies its check — inspect the

diff/layout, don't hand-wave. Full mode: open the pretty URL (emulate a mobile viewport, switch locale/RTL) to confirm; --lite/standalone: reason from the diff.

Declare a per-entry outcome in the summary (step 6), one token each: considerations: mobile ✓ · rtl n/a · cross-browser ⚠ (Safari flex-gap unchecked) — ✓ verified · n/a not applicable (one-word reason if non-obvious) · ⚠ applicable but unverified / needs follow-up (carry it into Considerations). Never omit the line when the list is non-empty; writing ✓ without actually checking is a contract violation.

3. Commit + push — explicit git, per repo

Stage only the files you changed (leave unrelated files untouched). Spell out git explicitly — do not delegate to a commit utility:

git -C "$WT" add  [ ...]
git -C "$WT" commit -m ""
git -C "$WT" push -u origin ""    # first push of the branch
git -C "$WT" push                          # subsequent iterations

4. Ensure the PR exists

Branch must be pushed first. On the first iteration create one PR per repo (gh infers the repo from the remote), targeting its base branch — configured base_branch in feature context, the repo's default base standalone:

( cd "$WT" && gh pr create --base  --title "" --body "" )
( cd "$WT" && gh pr view --json url -q .url )

Later iterations need nothing — the push already updated the open PR.

5. Persist dashboard artifacts — feature context only

Skip entirely when standalone. Overwrite //summary.md with the task's current cumulative state (what's done / considerations / what to test / links) in the user's language, using the structure the admin dashboard renders (- [ ] become click-persisted checkboxes):

# 

_updated  · iteration  · _

## What's done
- 
- simplify: ✓            # or: skipped (minor)
- considerations: mobile ✓ · rtl n/a · cross-browser ⚠   # omit only if the config list is empty

## Considerations / risks
- 

## What to test
- [ ] 

## Links
- PR : 
- Test: http://./

Then stamp the current session so the dashboard's "continue chat" is exact:

python3 - "$ROOT///.feature.json" "$CLAUDE_CODE_SESSION_ID" .pr` on first creation.

### 6. Chat output — now, and only now
Respond in the user's language. Blocks in this order, **ending with the test links** so they're the
last thing the user can click:

1. **What's done** — concise per-repo summary of this iteration. End with the simplify status line
   (`simplify: ✓` / `simplify: skipped (minor)`) and, when the config's `considerations` list is
   non-empty, the considerations line (`considerations: mobile ✓ · rtl n/a · …`).
2. **Considerations** — tied to this change: a cleaner/more correct approach, scenarios still
   uncovered, edge cases, and what's easy to forget (errors, empty/limit states, mobile, i18n,
   migrations, auth).
3. **🔗 Test / verify** — the LAST block.
   - *feature context:* clickable deep links that open exactly the affected page(s)/endpoint(s):
     `http://./` (+ `http://localhost:/…` fallback), API URLs for
     backend changes, and the PR link(s). Bare `http://…` per line with a short label. (If a server
     died, restart it and `--reload` the proxy first — see the `feature` skill.)
   - *standalone:* no app URLs — give how to verify (typecheck / build / unit test, or the key diff
     lines) + the PR link(s).

The next user prompt starts a new iteration → back to step 1.

## Red flags — STOP, you're about to break the contract
- "Too small to commit" → no. Every iteration commits (minor edits included).
- Said you'd simplify but didn't invoke `/simplify` → no. It must be a real skill invocation.
- Skipped the `considerations` line (non-empty config), or wrote `mobile ✓` without actually checking →
  no. Each applicable dimension must be really verified and reported (`✓`/`n/a`/`⚠`).
- About to write the summary before pushing → no. Push first, summary last.
- About to commit onto a base/default branch → no. Feature context: use the `task-` worktree
  branch. Standalone: branch off first.
- In feature context but skipping step 5 → no. summary.md + session stamp power the dashboard.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [fivol](https://github.com/fivol)
- **Source:** [fivol/claude-make-better](https://github.com/fivol/claude-make-better)
- **License:** MIT

Install and usage instructions live in the source repository linked above.