@graftsync/skill 0.1.1 → 0.1.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/SKILL.md +20 -4
- package/package.json +1 -1
package/SKILL.md
CHANGED
|
@@ -97,15 +97,31 @@ When asked to capture a modification as a graft (new, or migrating an existing p
|
|
|
97
97
|
2. **Write the intent first,** with the person who owns the modification if you can: *Why*,
|
|
98
98
|
the *Invariants* (observable behaviors, one per bullet), *Where to look* (by behavior), and
|
|
99
99
|
*Anchors* (what the variant matches on and why).
|
|
100
|
-
3. **Write the variant.** For `patch
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
100
|
+
3. **Write the variant.** For `patch`, make the change in the installed package
|
|
101
|
+
(`node_modules/<pkg>`), then run `graft capture <id>`: it writes the difference from the
|
|
102
|
+
published package as the variant (replacing the scaffold stub), and refuses binary changes.
|
|
103
|
+
**With pnpm**, don't edit `node_modules` in place (its files are hard links into the shared
|
|
104
|
+
store): run `pnpm patch <pkg>@<installed>`, edit the printed directory, `pnpm patch-commit
|
|
105
|
+
<dir> --patches-dir <tmp>`, and move the generated file onto `variants/v<major>.patch`
|
|
106
|
+
(`pnpm patch-commit` may also write a `package.json` entry; the next step replaces it).
|
|
104
107
|
4. **Apply it:** `graft apply`. This points the package manager at the
|
|
105
108
|
variant, reinstalls, and re-checks anchors.
|
|
106
109
|
5. **Write the oracle** so it fails before the modification and passes after. Check that it
|
|
107
110
|
fails without the graft. An oracle that can't fail proves nothing. Test the Invariants,
|
|
108
111
|
plus at least one pre-existing behavior the graft must not break.
|
|
112
|
+
- **Browser oracles** (Playwright etc.) fail on uncaught page errors, **`console.error`**
|
|
113
|
+
messages, and failed (5xx) requests. Frameworks catch errors and only log them:
|
|
114
|
+
Angular's `ErrorHandler`, React error boundaries, Vue's `errorHandler`. Listening only
|
|
115
|
+
for page errors lets a broken page pass.
|
|
116
|
+
- **Assert something visible that depends on the graft,** not only "no errors": a page can
|
|
117
|
+
fail to render without throwing.
|
|
118
|
+
- **Clean up what you start:** stop a dev server on *every* exit (`process.on('exit', …)`),
|
|
119
|
+
because `process.exit` skips `finally` blocks and leaves the port taken.
|
|
120
|
+
- **Test the code path, not the whole stack,** when the rest isn't what the graft changes.
|
|
121
|
+
For a dependency's browser behavior, load it through the dev server (e.g. a one-line
|
|
122
|
+
module importing it) instead of rendering pages through a framework's dev SSR.
|
|
123
|
+
- **Cover the modes the bug lives in.** A dev-only bug needs a `dev` mode; a production
|
|
124
|
+
build may behave differently (e.g. Vite replaces `process.env` only there).
|
|
109
125
|
6. **Prove it:** `graft verify <id>`, then `graft sync` (green).
|
|
110
126
|
7. **Find the variant's real range:** `graft replay <id>` checks every published version.
|
|
111
127
|
Record what you learn in *History*.
|