@ketecode/loom 0.1.0 → 0.2.0

package/skills/blender-automation/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: blender-automation
+description: Scripts Blender through its bpy Python API and command line - inspecting armatures, bone hierarchies, rest and pose transforms, constraints and vertex groups, diagnosing broken rigs and retargeted animation (wrong bone roll, scale on the armature, mismatched rest poses, missing action slots), editing actions and F-Curves through layers, strips and channelbags, batch-editing objects, materials and modifiers across many .blend files, and rendering headless with blender -b. Use when a rig or imported FBX animation looks wrong in Blender, when the same change must be applied to dozens of scenes or assets, or when renders must run from a script or on a farm without the UI.
+license: MIT
+compatibility: Any Agent Skills host. Needs a local Blender install on PATH (examples target Blender 4.4 and later, where actions use slots; 5.0 removed Action.fcurves). GPU rendering needs a supported GPU and driver.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "blender"
+  kete-loom/owner: "Kete-org"
+---
+
+# Blender automation
+
+Drive Blender from scripts so every change is repeatable, reviewable and can run without the UI. Inspect first, change on a copy, verify by reading the data back and rendering a check frame.
+
+## 0. Before you run anything
+
+1. Find the Blender version: `blender --version`. The Python API changes between releases; open the API docs for that exact version (`https://docs.blender.org/api/<major.minor>/`).
+2. Ask the user which `.blend` files are in scope and where outputs should go. **Work on copies**: never save over the user's originals unless they say so.
+3. Run scripts headless with an exit code on failure:
+
+   ```bash
+   blender -b --factory-startup scene.blend --python-exit-code 1 -P script.py -- --out /abs/out
+   ```
+
+   Arguments run in order: load the `.blend` first, then `-o` / `-F`, then `-f` or `-a`. Everything after `--` reaches the script via `sys.argv`. `--factory-startup` skips the user's startup file and add-ons, so enable add-ons the script needs explicitly.
+
+## 1. Inspect before changing
+
+Dump the facts into a text or JSON report rather than guessing from screenshots. Snippets in `references/bpy-inspection.md`:
+
+- Scene: objects, types, parents, collections, frame range, fps, render engine, output settings.
+- Armature: bones with parent, head, tail, roll, `use_deform`, `use_connect`, inherit scale mode; pose bones with rotation mode and constraints.
+- Mesh binding: Armature modifier target, vertex groups that have no matching deform bone, and deform bones with no vertex group.
+- Animation: each object's `animation_data.action`, `action_slot`, NLA tracks, and per-bone F-Curve key counts and frame range.
+- Object transforms: any non-applied scale or rotation on the armature or mesh object.
+
+## 2. Diagnose rigs and animation
+
+Work through `references/rig-and-retarget-checks.md`. The most common causes, in order:
+
+1. **Object scale or rotation not applied** on the armature (typical with FBX at 0.01 scale or a 90 degree X rotation). Animation then moves in the wrong units or axis.
+2. **Rest pose mismatch** between source and target (A-pose versus T-pose), so retargeted rotations are offset everywhere.
+3. **Bone roll differs** between rigs, so local rotation axes do not match and limbs twist.
+4. **Name mismatch**: F-Curve data paths like `pose.bones["mixamorig:LeftArm"].rotation_quaternion` do not match the target bone names, so channels silently do nothing.
+5. **Rotation mode mismatch**: curves on `rotation_euler` while the bone uses quaternions, or the reverse.
+6. **Action not assigned to a slot** (Blender 4.4+): the action is set but `animation_data.action_slot` is empty or targets a different ID, so nothing plays.
+7. **Constraints or IK** overriding the keyed pose, or bones with `inherit_scale` causing creeping scale.
+
+For each issue found, record: symptom, evidence (values read from the file), cause, fix. **Stop and show the user the diagnosis before changing a rig** that other files link to or that is shared by a team.
+
+## 3. Fix
+
+- Apply transforms with `bpy.ops.object.transform_apply` only on a copy, in Object mode with the object active and selected, and check the effect on its children and animation (applying scale to an animated armature changes what the location keys mean).
+- Rename bones or remap F-Curve data paths with a mapping table the user confirms; never guess a mapping for ambiguous bones (fingers, twist bones).
+- To retarget, prefer constraints (Copy Rotation in local space, or a dedicated retargeting add-on the user already uses) and bake to a new action (`bpy.ops.nla.bake` with `visual_keying=True`, `clear_constraints=True`), keeping the original action.
+- Edit keys through the layered action API (`references/bpy-inspection.md`, "Actions and F-Curves"). In Blender 5.0 and later, `Action.fcurves` no longer exists.
+
+## 4. Batch edits
+
+Pattern in `references/batch-and-render.md`:
+
+1. List the target files and print the plan (file, what will change) before changing anything.
+2. Open each file in a fresh Blender process (one `blender -b file.blend -P edit.py` per file) so state does not leak between files.
+3. Make the change through data (`bpy.data`), not operators, wherever possible; operators depend on context and selection.
+4. Save to an output folder with `bpy.ops.wm.save_as_mainfile(filepath=..., copy=True)`.
+5. Re-open each output and assert the change took effect; write a per-file result line (ok, skipped, failed with reason).
+
+## 5. Headless rendering
+
+```bash
+# one frame
+blender -b shot.blend -E CYCLES -o /abs/renders/shot_#### -F PNG -f 1
+# a range
+blender -b shot.blend -o /abs/renders/shot_#### -F OPEN_EXR -s 1 -e 240 -a
+```
+
+- `#` characters become the zero-padded frame number; `//` means relative to the `.blend`.
+- Pick the device and samples in a pre-render script (Cycles GPU setup in `references/batch-and-render.md`); without it Cycles uses whatever compute device that machine's saved preferences enable, and with `--factory-startup` that is the CPU.
+- List engine names with `blender -b -E help`; names differ across versions.
+- Render a single check frame and show it to the user before a long range or farm job.
+- Render image sequences, not a movie file, for anything long: a crash only loses one frame, and the sequence can be encoded afterwards with FFmpeg.
+
+## Never
+
+- Never overwrite the user's `.blend`, linked libraries or textures in place.
+- Never run scripts embedded in a `.blend` from an untrusted source (auto-run scripts stay off; never pass `-y` / `--enable-autoexec` for such files; pass `-Y` / `--disable-autoexec` to be explicit).
+- Never delete actions, bones or vertex groups without a backup and the user's approval.
+
+## Report back
+
+```
+Blender <version>   Files: n processed (ok / skipped / failed)
+Findings: <symptom> -> <cause> (evidence) -> <fix applied or proposed>
+Changed files: <output paths>      Renders: <path pattern, frames>
+Verification: values read back, check frame <path>
+Needs the user: mapping decisions, art direction, ...
+```

package/skills/blender-automation/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "My Mixamo animation retargeted onto our character in Blender has twisted arms and the feet slide",
+    "Write a bpy script that sets roughness on every material across 40 .blend files and saves copies",
+    "Render frames 1 to 240 of this .blend headless on the Linux render box with the GPU",
+    "Imported FBX rig is at 0.01 scale and lying on its side, and the action does nothing in Blender 4.4",
+    "Dump every bone, its roll and its vertex group from this armature so I can see why the mesh tears"
+  ],
+  "should_not_trigger": [
+    "Animate a 3D rotating cube proof with Manim for my maths lecture",
+    "Build a three.js scene that loads a glTF model in the browser",
+    "Turn this PNG image sequence into an MP4 at 24 fps",
+    "Generate a 3D product render from a text prompt with an image model",
+    "Edit the drone footage into a 90-second travel video with music"
+  ]
+}

package/skills/blender-automation/references/batch-and-render.md

@@ -0,0 +1,77 @@
+# Batch edits and rendering
+
+## Driver script (one Blender process per file)
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+mkdir -p out
+for f in assets/*.blend; do
+  blender -b --factory-startup "$f" --python-exit-code 1 -P edit.py -- "$PWD/out/$(basename "$f")" \
+    && echo "ok $f" || echo "FAILED $f"
+done
+```
+
+## edit.py pattern
+
+```python
+import bpy, sys
+out = sys.argv[sys.argv.index("--") + 1]
+
+changed = 0
+for mat in bpy.data.materials:
+    if not mat.use_nodes:
+        continue
+    bsdf = next((n for n in mat.node_tree.nodes if n.type == 'BSDF_PRINCIPLED'), None)
+    if bsdf:
+        bsdf.inputs["Roughness"].default_value = 0.6
+        changed += 1
+
+for ob in bpy.data.objects:
+    if ob.type == 'MESH' and not any(m.type == 'WEIGHTED_NORMAL' for m in ob.modifiers):
+        ob.modifiers.new("WeightedNormal", 'WEIGHTED_NORMAL')
+
+print(f"RESULT changed_materials={changed}")
+bpy.ops.wm.save_as_mainfile(filepath=out, copy=True)
+```
+
+Rules:
+- Socket names (such as "Roughness") and node types can change between versions; check the API docs for the installed version and fail loudly if a name is missing.
+- Prefer `bpy.data` edits over `bpy.ops`; when an operator is unavoidable, use `with bpy.context.temp_override(...)` to give it the context it needs.
+- Use `bpy.ops.wm.save_as_mainfile(..., copy=True)` so the open file name is not changed and originals are not touched.
+- Linked library data is read-only in the file that links it; edit the library file itself.
+
+## Cycles GPU pre-render script
+
+```python
+import bpy
+prefs = bpy.context.preferences.addons["cycles"].preferences
+prefs.compute_device_type = "OPTIX"   # or CUDA, HIP, METAL, ONEAPI, depending on hardware
+prefs.get_devices()
+for d in prefs.devices:
+    d.use = d.type != "CPU"
+scn = bpy.context.scene
+scn.render.engine = "CYCLES"
+scn.cycles.device = "GPU"
+scn.cycles.samples = 256
+scn.cycles.use_denoising = True
+```
+
+Use it with `blender -b shot.blend -P gpu.py -o /abs/renders/shot_#### -F PNG -a`. If no GPU device appears in `prefs.devices`, say so; do not silently fall back to a CPU render that will take hours.
+
+## Render settings from Python
+
+```python
+r = bpy.context.scene.render
+r.resolution_x, r.resolution_y, r.resolution_percentage = 1920, 1080, 100
+r.image_settings.file_format = "PNG"
+r.filepath = "//renders/shot_####"
+bpy.context.scene.frame_start, bpy.context.scene.frame_end = 1, 240
+bpy.ops.render.render(animation=True)
+```
+
+## Encode the sequence afterwards
+
+```bash
+ffmpeg -framerate 24 -i renders/shot_%04d.png -c:v libx264 -crf 18 -pix_fmt yuv420p shot.mp4
+```

package/skills/blender-automation/references/bpy-inspection.md

@@ -0,0 +1,91 @@
+# bpy inspection snippets
+
+Run with `blender -b file.blend --python-exit-code 1 -P inspect.py -- out.json`.
+
+## Scene and objects
+
+```python
+import bpy, json, sys
+out = sys.argv[sys.argv.index("--") + 1]
+scn = bpy.context.scene
+report = {
+    "blender": bpy.app.version_string,
+    "frame_range": [scn.frame_start, scn.frame_end], "fps": scn.render.fps / scn.render.fps_base,
+    "engine": scn.render.engine, "output": scn.render.filepath,
+    "objects": [{
+        "name": o.name, "type": o.type, "parent": o.parent.name if o.parent else None,
+        "location": list(o.location), "rotation": list(o.rotation_euler), "scale": list(o.scale),
+        "collections": [c.name for c in o.users_collection],
+    } for o in bpy.data.objects],
+}
+json.dump(report, open(out, "w"), indent=2)
+```
+
+## Armature, bones and pose
+
+```python
+arm = bpy.data.objects["Armature"]
+for b in arm.data.bones:            # rest data (edit-bone values, read-only here)
+    print(b.name, b.parent.name if b.parent else None, tuple(b.head_local), tuple(b.tail_local),
+          b.use_deform, b.use_connect, b.inherit_scale)
+for pb in arm.pose.bones:           # pose data
+    print(pb.name, pb.rotation_mode, [c.type for c in pb.constraints], tuple(pb.matrix_basis.to_euler()))
+```
+
+Bone roll is only exposed on edit bones: switch to Edit mode on the armature (`bpy.ops.object.mode_set(mode='EDIT')` with it active) and read `arm.data.edit_bones[name].roll`, then return to Object mode.
+
+## Vertex groups versus deform bones
+
+```python
+mesh = bpy.data.objects["Body"]
+deform = {b.name for b in arm.data.bones if b.use_deform}
+groups = {g.name for g in mesh.vertex_groups}
+print("groups without bone:", sorted(groups - deform))
+print("deform bones without group:", sorted(deform - groups))
+print("armature modifiers:", [(m.name, m.object.name if m.object else None) for m in mesh.modifiers if m.type == 'ARMATURE'])
+```
+
+## Actions and F-Curves (Blender 4.4+ layered actions)
+
+Actions hold layers, layers hold strips, and a keyframe strip holds one channelbag per slot. `Action.fcurves` was removed in 5.0.
+
+```python
+ad = arm.animation_data
+act, slot = ad.action, ad.action_slot
+print(act.name if act else None, slot.identifier if slot else None, [s.identifier for s in act.slots])
+
+from bpy_extras import anim_utils
+bag = anim_utils.action_get_channelbag_for_slot(act, slot)   # None if the slot has no keys
+for fc in bag.fcurves:
+    keys = fc.keyframe_points
+    print(fc.data_path, fc.array_index, len(keys), keys[0].co.x if keys else None, keys[-1].co.x if keys else None)
+```
+
+If `action_get_channelbag_for_slot` is missing in the installed version, walk it directly: `act.layers[0].strips[0].channelbag(slot)`.
+
+Remap bone names in data paths (after the user confirms the mapping):
+
+```python
+mapping = {"mixamorig:LeftArm": "upper_arm.L"}
+for fc in bag.fcurves:
+    for src, dst in mapping.items():
+        token = f'pose.bones["{src}"]'
+        if fc.data_path.startswith(token):
+            fc.data_path = fc.data_path.replace(token, f'pose.bones["{dst}"]', 1)
+```
+
+Assign an action and its slot:
+
+```python
+ad = arm.animation_data or arm.animation_data_create()
+ad.action = act
+if ad.action_slot is None and act.slots:
+    ad.action_slot = act.slots[0]
+```
+
+## NLA
+
+```python
+for t in ad.nla_tracks:
+    print(t.name, t.mute, [(s.name, s.action.name, s.frame_start, s.frame_end) for s in t.strips])
+```

package/skills/blender-automation/references/rig-and-retarget-checks.md

@@ -0,0 +1,23 @@
+# Rig and retarget checks
+
+Work top to bottom. For each, read the values with the inspection snippets; do not judge from a viewport screenshot alone.
+
+| # | Symptom | Check | Typical fix |
+|---|---|---|---|
+| 1 | Character tiny, huge, lying down, or root motion in wrong units | Armature and mesh object `scale` not 1, or `rotation_euler.x` near 1.5708 (FBX import) | On a copy, apply rotation and scale (`transform_apply(location=False, rotation=True, scale=True)`), or re-import FBX with Apply Transform or a unit scale the user confirms; re-check location keys after |
+| 2 | Every limb offset by the same amount after retarget | Rest poses differ (A-pose vs T-pose): compare `bone.matrix_local` of matching bones | Retarget with constraints in local or pose space and bake, or adjust the source rest pose to match before baking |
+| 3 | Limbs twist or rotate around the wrong axis | Edit-bone `roll` differs for matching bones | Match roll on the target only if it is not yet skinned or the user accepts re-weighting; otherwise retarget in world or pose space |
+| 4 | Some bones do not move | F-Curve data paths name bones that are not in the target | Rename bones or remap data paths with a confirmed mapping |
+| 5 | Bones move but rotate wrongly or jitter | Curves on `rotation_euler` but `rotation_mode` is `QUATERNION`, or the reverse; quaternion sign flips between keys | Set `rotation_mode` to match the curves, or convert and bake; fix sign flips by negating the quaternion on flipped keys |
+| 6 | Action assigned but nothing plays (4.4+) | `animation_data.action_slot` is None or its `target_id_type` does not match | Assign the right slot |
+| 7 | NLA or another action overrides the keys | NLA tracks not muted, action influence, or tweak mode | Mute or remove tracks on a copy; push the action to an NLA strip deliberately |
+| 8 | Pose ignores keys | Constraints (IK, Child Of, Copy Transforms) with influence 1 | Check each constraint's influence and target; bake visual transforms if the constraints are only for retargeting |
+| 9 | Mesh tears or parts stay behind | Vertex groups with no matching deform bone, `use_deform` off, Armature modifier missing or on the wrong object, or modifier order (Armature after a Subdivision) | Fix names and flags; move the Armature modifier to the top of the stack |
+| 10 | Creeping scale down a chain | `inherit_scale` and scale keys on parent bones | Remove scale keys that should not exist; set inherit scale as the rig design requires |
+| 11 | Foot sliding after retarget | Different leg lengths between rigs | Scale root motion by the leg-length ratio, or use IK for feet and bake |
+
+Verification after any fix:
+
+1. Read the changed values back from the saved copy.
+2. Render or capture three frames (first, middle, last of the action) from a fixed camera and compare with the source.
+3. Report key counts per bone before and after a bake; a bake should not drop channels unexpectedly.

package/skills/brand-strategy/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: brand-strategy
+description: Brand identity strategy run as a structured interview, one question block at a time, covering purpose, positioning against named alternatives, the primary audience and their job to be done, three to five values tied to behaviours, personality traits and a naming brief, then written up as a one-page brand brief with open questions marked. Use when a founder or team is starting or rebranding a company or product and needs its positioning, audience, values and personality decided before voice guides, names, logos or campaigns are made.
+license: MIT
+compatibility: Any Agent Skills host. No tools needed beyond reading what the user shares and writing the brief.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: business
+  kete-loom/risk: writes-files
+  kete-loom/owner: "Kete-org"
+---
+
+# Brand strategy
+
+Turn what the founders know (and argue about) into a short brand brief that later work can build on: the `brand-voice` guide, a naming round, a logo brief, a `marketing-campaign` plan. The brief records decisions, not adjectives.
+
+## Ground rules
+
+1. **Interview, don't invent.** Every line in the brief traces to something the user said or chose. Where you propose wording, mark it as a proposal until they accept it.
+2. **One block at a time.** Ask the questions for one block, wait, play back what you heard in two or three lines, then move on. Never send all the questions at once.
+3. **Specific beats aspirational.** "Innovative, trusted, customer-first" fits every company and decides nothing. Push each answer until it would exclude someone or something.
+4. **Name the alternative.** Positioning only means something against what the customer would do instead (a named competitor, a spreadsheet, a cousin who does it for free, doing nothing).
+5. **Evidence over hope.** If an answer about customers is a guess, say so and record it as an assumption to test, not a fact.
+
+## Before you start
+
+Ask for anything that already exists: pitch deck, website, customer interviews, reviews, sales call notes, a competitor list, an earlier brand doc. Read it first and skip questions it already answers; confirm those answers instead of asking again.
+
+Confirm the scope: a company brand, a product brand under a parent, or a rebrand. For a rebrand, ask what is wrong with the current brand and what must survive (name, colour, equity customers recognise).
+
+## The interview
+
+Work through these blocks in order. Each has a goal; the questions are a starting point, so follow up where answers are vague.
+
+1. **Purpose.** Why the business exists beyond revenue, and what changes for customers if it succeeds. Ask: "What would your best customers lose if you shut down tomorrow?" and "What do you refuse to do even if it would make money?"
+2. **Audience.** One primary audience, described by situation and job to be done, not demographics alone. Ask who buys, who uses, who blocks the purchase, what triggers them to look for a solution, and what they use today. If they name three equal audiences, ask which one they would serve if they could only serve one.
+3. **Positioning.** Fill the frame: *For [audience] who [need or trigger], [brand] is the [category] that [key benefit], unlike [named alternative], because [reason to believe].* Ask for the proof behind the "because" (a feature, a number, a process, a founder fact).
+4. **Values.** Three to five values, each with a behaviour that shows it and a trade-off it implies ("Plain speaking: we tell customers about a fee before they find it, even when it costs a sale"). Drop any value nobody can give a behaviour for.
+5. **Personality.** Three to five traits as "this, not that" pairs on sliders (playful to serious, expert to peer, bold to calm). Ask: "If the brand were a person at a dinner party, who would it be, and who would it never be?" This feeds `brand-voice`; do not write the voice guide here.
+6. **Naming brief** (only if a name is needed or under review). Capture what the name must signal, what it must avoid, markets and languages it must work in, the preferred name type (descriptive, invented, metaphor, founder, acronym), length, and must-haves such as a .com or a matching handle. Generate candidates only if asked, and never present one as available.
+7. **Proof and constraints.** Claims the brand can make today with evidence, claims it cannot make yet, regulatory limits on claims in its sector, and existing assets that must be kept.
+
+## Decision rules
+
+- Two founders disagree on a block: record both positions side by side and ask them to choose. Do not average them into a vague middle.
+- The user wants to be everything to everyone: show what each audience would need the positioning to say; usually the conflict makes the choice obvious.
+- No reason to believe exists yet: keep the positioning but list the proof as a gap to build.
+- A value or trait contradicts how the business actually behaves (for example "transparent" with hidden fees): say so plainly and ask which one changes.
+
+## Stop and ask the user
+
+- Before writing the brief, if any of purpose, primary audience or positioning is still undecided.
+- Before suggesting a name be used publicly: trademark clearance and domain checks are needed, and clearance in each market is a job for a trademark professional, not this skill.
+- If a positioning claim is a comparative or health, financial or environmental claim, flag that it may need legal review before it is published.
+
+## Never
+
+- Never fill the brief with stock adjectives the user did not choose.
+- Never claim a name is free to use, trademarked or not, or that a domain is available, without a check the user can see.
+- Never design logos, colour palettes or typography here; write the brief a designer would work from.
+
+## Output: the brand brief
+
+Write one page in Markdown (to a file if the user wants one), in this shape:
+
+```
+# <Brand> brand brief  (v<n>, <date>)
+
+Purpose: <one sentence>
+Primary audience: <situation + job to be done>; secondary: <if any>
+Positioning: For ... who ..., <brand> is the ... that ..., unlike ..., because ...
+Proof: <evidence for the "because">; gaps: <proof still to build>
+Values: <value>: <behaviour> / <trade-off>   (3-5 lines)
+Personality: <this, not that>   (3-5 pairs)
+Naming brief: <must signal / must avoid / markets / type / constraints>  (if in scope)
+Can claim today: ...   Cannot claim yet: ...
+Keep from current brand: ...
+Assumptions to test: ...
+Open questions: ...
+Next: brand-voice guide, naming round, visual identity brief, campaign plan
+```
+
+Close by listing which open questions block the next step, and which items are proposals the user has not yet accepted.

package/skills/brand-strategy/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "We're launching a new fintech startup and haven't decided who we're really for or how we're different. Can you interview us and write a brand brief?",
+    "Help me work out our brand positioning statement against the big banks and mobile money apps",
+    "We're rebranding our bakery chain. Walk us through purpose, values and personality before we hire a designer.",
+    "My co-founder and I disagree on what our brand stands for. Run a structured brand workshop with us.",
+    "Write a naming brief for our new product line so an agency can start generating names"
+  ],
+  "should_not_trigger": [
+    "Create a voice and tone guide with do and don't rewrites for our support team",
+    "Size the market for our school management software in Nigeria with TAM, SAM and SOM",
+    "Plan the four-week launch campaign for our new app with a budget split",
+    "Design a logo and a colour palette for our coffee shop",
+    "Does this homepage copy sound like our brand? Here is the style guide."
+  ]
+}

package/skills/change-impact-analysis/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: change-impact-analysis
+description: Blast-radius analysis for a code change, built from the real dependency graph rather than guesswork, using import search, the build graph and monorepo tooling (nx affected, turbo --affected, bazel query rdeps, go list, pnpm filters, Maven -amd, Gradle buildDependents) to find downstream consumers, then running the tests of changed modules and every dependent, and reconciling the predicted impact against the actual diff. Use when asked what a change could break, which packages or services consume a module, which tests must run for a diff, or whether a shared library edit is safe to merge.
+license: MIT
+compatibility: Any Agent Skills host. Needs git and the project's own build or test tooling; monorepo commands apply only where that tool is already in use.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "git"
+  kete-loom/owner: "Kete-org"
+---
+
+# Change impact analysis
+
+Answer "what can this change break?" with evidence: a list of consumers found from the dependency graph, the tests that cover them, and the results of running those tests. Never answer from intuition alone.
+
+## When to run it
+
+- **Before** a change: predict impact so the plan and the review cover every consumer.
+- **After** a diff exists: compute actual impact, run the affected tests, compare with the prediction.
+- Both, for shared libraries, public APIs, database schemas, config keys and anything published.
+
+## 1. Pin down the change
+
+1. Get the changed files: `git diff --name-only <base>...HEAD` (base is usually `origin/main`; use the merge base, not the tip). Include untracked files from `git status --short`.
+2. For each file, list the changed **symbols**: exported functions, classes, types, routes, events, CLI flags, env vars, config keys, DB columns, message schemas. A file-level graph over-reports; symbols tell you which consumers really care.
+3. Classify each symbol change: internal only, signature change, behaviour change with the same signature, removal, or new addition. Additions rarely break consumers; behaviour changes are the ones people miss.
+
+## 2. Build the consumer graph from the tooling the repo already has
+
+Detect the build system first (look for `nx.json`, `turbo.json`, `WORKSPACE`/`MODULE.bazel`, `go.mod`, `pnpm-workspace.yaml`, `pom.xml`, `settings.gradle(.kts)`, `Cargo.toml` workspaces). Use the tool's own graph; it knows about generated code and path aliases that grep misses. Commands are in `references/graph-commands.md`.
+
+- **Monorepo tool present**: ask it for affected projects between base and head (for example `nx show projects --affected -t test --base=origin/main`, `turbo run test --affected`, `bazel query "rdeps(//..., //pkg:target)"`).
+- **No graph tool**: search the codebase for imports of the changed module and for each changed symbol name, then repeat one level up for every hit until no new consumers appear. Note this is a search result, not a graph.
+- **Outside the code graph** (tools can't see these, search for them by name):
+  - string-keyed references: route paths, event or queue names, feature-flag keys, env vars, config keys, SQL column names, reflection and dependency-injection names;
+  - other repositories, deployed services, mobile apps on old versions, and third parties that call a public API;
+  - generated clients, fixtures, snapshots, docs and examples that embed the old shape;
+  - CI, deploy and infrastructure files that reference changed paths.
+
+## 3. Rate the blast radius
+
+For each consumer record: name, how it depends (import, HTTP, event, schema, config), what it uses, and risk:
+
+| Risk | Meaning |
+|---|---|
+| High | Uses a removed or changed signature or behaviour; deployed separately; no tests cover the usage |
+| Medium | Uses the changed symbol, tests exist and will run |
+| Low | Depends on the package but not on the changed symbols |
+
+**Stop and ask the user** when a High consumer is outside this repository, when the change touches a published package, public API, database schema or message format, or when the graph says more than about 20 projects are affected (confirm the change should be split or staged).
+
+## 4. Run the affected tests
+
+1. Run the tests of the changed modules first, then every downstream consumer. Use the tool's affected mode (`nx affected -t test`, `turbo run test --affected`, `bazel test` on the rdeps test set, `go test` on the reverse-dependency packages, `mvn -pl <module> -amd verify`, `./gradlew :<module>:buildDependents`).
+2. Inside a single package, narrow with the runner's related-test mode where it exists (`jest --findRelatedTests <files>`, `vitest related <files> --run`, `pytest --testmon` if pytest-testmon is installed), and still run the full package suite before calling it safe.
+3. Include type-checks and builds of consumers; a signature change often breaks compilation, not tests.
+4. If a consumer has **no** test touching the changed symbol, list it as a coverage gap. Do not report it as safe.
+5. Shallow CI clones make affected detection treat everything as changed or nothing as changed; fetch enough history for the base.
+
+## 5. Reconcile planned vs actual
+
+After the diff is final, rerun step 1 and step 2 and compare with the prediction:
+
+- Files or symbols changed that the plan didn't mention: explain each or flag it as scope creep.
+- Consumers predicted but not actually affected: fine, note them.
+- Consumers affected but not predicted: these are the important ones; run their tests and add them to the review.
+
+## Never
+
+- Never declare a change safe because one package's tests pass.
+- Never skip consumers outside the build graph because the tool didn't list them.
+- Never edit consumers to make the analysis pass without telling the user; that's a new change.
+
+## Report
+
+```
+## Impact: <change>
+Base: <ref>  Head: <ref>
+Changed symbols: <symbol> (<kind of change>) ...
+Consumers
+- <name> | via <import/http/event/schema/config> | uses <symbol> | risk High/Med/Low | tests: <ran: pass/fail | none>
+Outside the graph: <string-keyed refs, other repos, external callers, or "none found">
+Commands run: <command> -> <result>
+Coverage gaps: <consumer: what is untested>
+Planned vs actual: <unplanned changes, unpredicted consumers, or "matches">
+Verdict: safe to merge | merge after <action> | needs staged rollout or split
+```

package/skills/change-impact-analysis/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "I changed the signature of formatCurrency in packages/shared-utils. Which apps in the monorepo use it and could break?",
+    "What's the blast radius of renaming the user_status column? Find every consumer before I merge.",
+    "Run nx affected for my branch and tell me which downstream projects need testing",
+    "Before I bump the logging library interface, map every service and package that depends on it and run their tests",
+    "My diff ended up touching more than I planned. Compare what I expected to affect against what actually changed."
+  ],
+  "should_not_trigger": [
+    "Break this feature request into ordered implementation steps before I start coding",
+    "Rename the parseDate helper across the codebase without changing behaviour",
+    "Run lint, type-check and the test suite before I open a pull request",
+    "Scan our npm dependencies for known vulnerabilities",
+    "Explain how this repository is structured, I just cloned it"
+  ]
+}

package/skills/change-impact-analysis/references/graph-commands.md

@@ -0,0 +1,28 @@
+# Dependency graph commands by build system
+
+Use only the tool the repository already uses. Check flags against the installed version with `--help`.
+
+| Tool | Affected or reverse-dependency query | Run affected tests |
+|---|---|---|
+| Nx | `nx show projects --affected -t test --base=origin/main --head=HEAD`; `nx graph --affected` to view | `nx affected -t test --base=origin/main --head=HEAD` (or set `NX_BASE` / `NX_HEAD`) |
+| Turborepo | `turbo run test --affected --dry-run` lists tasks; `--filter=...[origin/main]` selects changed packages and their dependents | `turbo run test --affected` (base defaults to `main`; override with `TURBO_SCM_BASE`, head with `TURBO_SCM_HEAD`) |
+| Bazel | `bazel query "rdeps(//..., //path/to:target)"`; tests only: `bazel query "kind('.*_test', rdeps(//..., //path/to:target))"` | `bazel test $(bazel query "kind('.*_test', rdeps(//..., //path/to:target))")` |
+| Go modules | No built-in reverse lookup. `go list -test -f '{{.ImportPath}} {{join .Deps " "}}' ./... \| grep -E ' <changed/import/path>( \|$)' \| awk '{print $1}' \| grep -v '\.test$' \| sort -u` lists packages whose code or tests depend on it directly or transitively; add the changed package itself | `go test <listed packages>` plus `go vet` |
+| pnpm workspaces | `pnpm --filter "...[origin/main]" list --depth -1` (changed packages and their dependents); `pnpm --filter "...<pkg>"` for one package | `pnpm --filter "...[origin/main]" test` |
+| Maven | `mvn -pl <module> -amd validate` prints the dependents in the Reactor Build Order (don't pass `-q`, it hides that list) | `mvn -pl <module> -amd verify` |
+| Gradle | No built-in reverse-dependency listing; `buildDependents` runs them | `./gradlew :<module>:buildDependents` (builds and tests the project and every project that depends on it) |
+| Cargo workspace | `cargo tree -i <crate> --workspace` (inverted tree) | `cargo test -p <crate> -p <each dependent>` |
+| Python (no monorepo tool) | Search imports: `git grep -nE "^(from\|import) <package>"`; `pipdeptree -r -p <dist>` for installed distributions | `pytest <dirs>`; `pytest --testmon` with pytest-testmon for test-level selection |
+
+## Related-test modes inside one package
+
+- Jest: `jest --findRelatedTests <changed files>`, `jest --changedSince=origin/main`
+- Vitest: `vitest related <changed files> --run`, `vitest --changed origin/main`
+- Go: `go test ./<pkg>/...` is already scoped; there is no file-level mode.
+
+These follow static imports only. Dynamic imports, string-keyed lookups, DI containers and reflection need a codebase search.
+
+## CI notes
+
+- Fetch enough history to contain the merge base (`fetch-depth: 0`, or a blobless clone with `--filter=blob:none`); a too-shallow clone makes turbo treat every package as changed.
+- Use the last green commit on the default branch as the base when the tool supports it (Nx recommends this).