| name | report-tool-friction |
| description | This skill should be used whenever a PulseEngine tool (rivet, spar, witness, sigil, meld, loom, synth, kiln, gale, scry, smithy, thrum, temper, mcp — the roster lives in the pulseengine-toolchain memory) produces friction during real work — it errors, crashes, produces wrong or surprising output, is missing a capability you needed, has confusing/undocumented behavior, or forced you into a workaround. ALWAYS use this skill the moment you notice yourself working *around* a tool instead of *with* it, or saying "this should just work but doesn't." The friction is the signal; capturing it as an issue in the tool's own repo is the action. Fires inside [`pulseengine-feature-loop`] and [`release-execution`] and any standalone tool use. |
| metadata | {"author":"pulseengine.eu","version":"0.1.0"} |
Report tool friction
When this fires
You are using a PulseEngine tool to get real work done — not testing the tool, just using it — and it gets in your way. Concretely, any of:
- It errors, panics, or crashes on input that should be valid.
- It produces wrong, surprising, or unexplained output.
- It's missing a capability the task needed, so you reached for something else.
- Its behavior was confusing or undocumented enough that you had to guess.
- You wrote a workaround — a manual step, a shim, a
|| true, a hand-edit of generated output, a "do it outside the tool for now."
The moment you notice the workaround is the trigger. A workaround you don't report is friction the next person re-hits. Dogfooding only improves the tools if the friction becomes a tracked, fixable artifact.
This is a standing practice woven through all tool use, not a phase. It fires as you work, not at a checkpoint.
Procedure
1. Identify the right repo
File in the tool's own repo (pulseengine/<tool>), not in the consuming project. If rivet misbehaves while you're shipping spar, the issue goes to pulseengine/rivet. If you can't tell which tool owns the friction, file in the one you invoked and cross-link.
2. Search for a duplicate first
gh issue list --repo pulseengine/<tool> --search "<key phrase>" --state all. If an open issue already covers it, add a comment with your fresh repro instead of opening a new one. Label-search for the friction label too.
3. File it automatically, then mention it
Open the issue without pausing the work, then note it in your response to the user (link + one line). Don't batch, don't wait for permission — friction is cheap to capture and expensive to forget. The body, kept short:
**What I was trying to do:** <the real task, one or two sentences>
**Tool + version:** <tool> <version / commit / "source @ <sha>">
**What happened:** <the error / wrong output / missing capability>
**Repro:** <the exact command(s) or input, minimal>
**Workaround used (if any):** <what I did instead, so the next person isn't blocked>
**Impact:** <blocked / slowed / cosmetic — be honest>
Use a consistent label so these are filterable and reviewable as a batch later:
gh issue create --repo pulseengine/<tool> \
--title "friction: <short description>" \
--label tool-friction \
--body-file <body>
gh label create tool-friction --color fbbf24 --description "Friction hit while using the tool for real work (dogfooding signal)" --force
4. Keep moving
Filing the issue is not a stop point. Note the workaround in the issue, apply it, and continue the task. The issue is the durable record; the work doesn't wait on the fix.
What makes a good friction issue
- The real task is in it. "rivet check failed" is noise; "rivet check rejected a valid
verifies link between a test and a sec-constraint while shipping spar v0.9" is signal — it tells the maintainer what use-case broke.
- Minimal repro. The smallest command/input that reproduces. If you can't minimize quickly, paste what you have and say so.
- Honest impact. Cosmetic friction and blocking friction need different triage. Don't inflate; don't omit.
- The workaround is recorded. Even a bad workaround is information — it shows what the tool failed to make easy.
Anti-patterns
- Silent workarounds. The single failure mode this skill exists to kill. If you worked around a tool and didn't file, the friction is now invisible.
- Batching everything to the end of the session. You forget the specifics; repros decay. File when you hit it.
- Filing in the consuming repo instead of the tool repo. The fix lives where the tool lives.
- Filing without searching for a dupe. Noise erodes the signal of the
tool-friction label.
- Turning every preference into friction. Friction is "the tool failed at what it's for," not "I'd have designed it differently." Disagreements about design are a different conversation.
- Pausing the real work to perfect the issue. Capture, link, continue. A terse-but-real issue beats a polished one you never filed.
Where this composes
- [
pulseengine-feature-loop] — friction surfaces at every step (spar passes, rivet validate, witness gaps, sigil verify); report it inline as you go.
- [
release-execution] — the release-tail is where deferred friction tends to accumulate; the traceability completeness gate often surfaces tool gaps. File them rather than carrying them in your head.
- [
oracle-gate-a-change] — when the oracle itself is the tool that's broken (the check won't run, or runs wrong), that's friction in the verifier — report it; a broken oracle is worse than a missing one.
