refresh

Files (1)

• SKILL.md

SKILL.md (first lines)

# Refresh rules for a framework version

Clawness rules can carry a version stamp — `applies_to`, `verified`, `sources` —
recording the range they were established against. When a project runs past that
range, a SessionStart note says so once and deliberately does nothing else.

This skill is the **remedy**. The note is only the diagnosis: it fires before you
have said what you came for, so it cannot propose a session's worth of destructive
work. You invoking this skill *is* the consent it couldn't ask for.

**This is the only path permitted to author rule files.** Nothing automatic may
invoke it — not the note, not a hook, not your own initiative mid-task. An earlier
version of this feature let the automatic path write rules and it produced heaps of
them, consuming a session opened for something else.

**Say this before starting.** It takes a while, it writes files into the project,
and the rules it writes will govern every future prompt in this repo. Get an
explicit go-ahead, and tell them nothing is written until they approve the list.

## Argument

`/clawness:refresh <domain>` — one domain (`nextjs`, `react`, `python`, `fastapi`,
…). With no argument, use the detected stack, and if that spans several domains ask
which one. **One domain per run.** Reviewing several at once is how a careful pass
becomes a bulk stamp, which is the failure this whole feature exists to prevent.

## Steps

### 1. Establish what is actually installed

The **lockfile is authoritative; the manifest range is not.** `^17.0.0` in
`package.json` is a permission, not a fact — read `package-lock.json`,
`pnpm-lock.yaml`, `yarn.lock`, `uv.lock`, `poetry.lock`, or `pip freeze` output for
the resolved version. This is `GEN-INSTALLED-VER-001`'s procedure, and it matters
more here than usual: the rule you write will be asserted to future sessions as
fact.

If you cannot resolve an exact version, say so and stop. Do not write a rule
against a version you had to guess.

### 2. Establish what the codebase actually uses

Version alone is not the answer. A Next.js 17 project still on the Pages Router
must not be given App Router rules, and a project that never touches the changed
API needs no rule at all.

Grep for the constructs each candidate rule would govern **before** writing it. A
rule that doesn't apply here is not harmless — it competes for a top-k slot on
every prompt, forever, and displaces one that does apply.

### 3. Look up what changed

Between the stamped range and the installed major. Prefer, in order:

1. The framework's own migration guide / upgrade guide for that major.
2. The official changelog or release notes.
3. The current official docs page for the API in question.

**Not recalled knowledge.** A model's sense of "what's current" lags real releases
by exactly the gap this feature exists to close — using it here would launder a
guess into a stamped, sourced rule, which is worse than the stale rule you started
with. If you cannot reach documentation, report that and stop.

Record the URL you used for each finding. It becomes the rule's `sources`, and it
is what makes a generated stamp auditable rather than asserted.

*(This step is shared with `clawness audit-rules`' review pass — same lookup,
different destination: this writes to one project, that fixes the corpus upstream.)*

### 4. Classify each rule in the domain

Read every rule in the domain, global and project. For each, one verdict:

| Verdict | Action |
| --- | --- |
| **Still true** at the installed version | Nothing. Say so — the honest majority. |
| **Changed** | Override under its **own id** (see below). |
| **Now the framework default** | Override to say so, or drop it — a rule telling you to do what the framework already does is pure noise. |
| **New concept, no rule exists** | New id, new rule. |
| **Can't settle it** | Leave alone, report as unsettled. A gap is truthful; a guess is not. |

### 5. Report the list and stop

Present the classification as a table with the proposed id, verdict, and source URL
for each. **Write nothing until the user approves.**

Cap what you propose at **6 rule files** unless the user asks for more. That number
is a judgment call, not a measurement: it is small enough that the review stays a
review, and a major migration that genuinely needs more is a conversation worth
having rather than a batch to wave through. If more than six rules are affected,
propose the six that matter most and say what you left out.

### 6. Write the approved overrides

Into `<project>/.clawness/rules/<domain>/<ID>.yml`.

**Override a superseded rule under its OWN id.** `NX-ROUTE-001` for v17 replaces
`NX-ROUTE-001` for v14. A new id would leave both in the corpus, one describing 14
and one 17, competing for the same slot — strictly worse than the stale rule alone.
`add_rules` replaces by id, so the project copy wins outright. A genuinely new
concept with no existing rule does get a new id.

Full rule format, plus the stamp:

```yaml
id: NX-ROUTE-001
domain: nextjs
severity: warning
tags: [routing, app-router]
triggers: [route, app router, layout]
when: Defining routes in this project.
rule: <what to do, precisely, at the installed version>
violation: <the v14 shape, if it helps>
correct: <the v17 shape>
applies_to: {"Next.js": "17"}
verified: "<YYYY-MM, this month>"
sources: ["<the URL from step 3>"]
# Generated by /clawness:refresh for Next.js 17 on <YYYY-MM-DD>.
```

From fullymiddleaged/Clawness, MIT.

More from fullymiddleaged/Clawness