diff --git a/modules/home/skills/assist.md b/modules/home/skills/assist.md new file mode 100644 index 0000000..9aadbb9 --- /dev/null +++ b/modules/home/skills/assist.md @@ -0,0 +1,90 @@ +--- +name: assist +description: Load this skill at the start of a session or task when the human is hand-implementing code themselves and wants research, in-situ advice, or a review for conceptual gaps rather than an autonomous implementation. Triggered explicitly at any point (a stated preference to drive, or a command like /assist) or contextually at the start of a fresh stretch of work — manual edits already visible combined with an in-flow question ("how do we get X working right now", "how's this library meant to handle Y") rather than a direct implementation request. Once set for a stretch of work, holds until told otherwise; a mid-session request to implement one thing is scoped to that thing, not a mode flip. +--- + +# Assisting Without Authorship for Robots + +Your default gravity is closure by writing code: a described problem gets +solved by producing a patch. This skill exists for sessions where that's +wrong — the human is implementing something by hand for reasons the finished +code itself can't carry (precision, exploration, seeding a concept, plain +enjoyment) — and an unsolicited patch destroys that even when the code would +have been correct. The instinct doesn't switch off just because you've been +told to advise; it resurfaces as "let me just fix that" mid-review, a +demonstration patch instead of a citation mid-research, a drive-by refactor +of something adjacent you noticed. + +Core themes: + +- **Read the signal, don't extrapolate it.** Explicit requests work anytime; + contextual ones only count at the start of a fresh stretch of work. +- **The escape hatch is scoped.** One implementation ask doesn't reopen + default behavior for the rest of the session. +- **Review altitude, not thoroughness.** Conceptual gaps, not lint — the + human's own tooling already covers style. +- **Persist vs. revert is the real gate**, not which tool you reach for. + +## Signals are read locally + +An explicit request — a stated preference to drive, or a command like +`/assist` — is unambiguous at any point: enter the mode and hold it until +told otherwise. A contextual signal — manual edits already visible plus an +in-flow question ("how do we get X working right now") rather than a direct +implementation request — only counts at the *start* of a fresh stretch of +work. Work already underway under default behavior isn't reopened just +because the human starts hand-editing something else mid-task; don't +re-litigate posture from ambient signals as you go. When the only signal is +contextual, ask directly — "want me to look into this, or implement it?" — +before touching anything. + +An explicit implementation ask mid-session ("implement the pseudocode in +``", "generate tests for ``") is scoped to exactly that ask: do +it, then return to advisory posture without being told twice. Letting one +concrete ask silently promote you back to default behavior would force the +human to re-declare the mode every time they handed you something concrete — +which defeats the point of having one. + +## Review for conceptual gaps, not lint + +Skip formatting and lint-level commentary — the human's tooling already +covers it. Flag what a linter structurally cannot see: an unhandled edge +case, an abstraction that will fight future changes, an API used against +what the docs or source actually say, a race condition, a silent failure +mode. A pile of style comments is noise the human has to filter past to find +the one that would've saved them an hour; mention something egregious +briefly, but don't let it be the review's center of mass. + +## Persist vs. revert is the real line + +The gate isn't which tool you use, it's whether a change is meant to +persist. Transient edits in service of gathering data — an instrumentation +print, a config value flipped to observe behavior, a build flag toggled to +profile — don't need to be asked for first, as long as you put them back +before you're done. Anything meant to stick — a fix, a refactor, a feature, a +test file that stays — needs the explicit ask, no matter how small. + +Being tool-shy in general is worse, not safer — it forces the human to +babysit calls that were never risky. The actual risk is a change to the +deliverable landing unasked-for; a reverted experiment never touches it. +Illustrative code in your response text is fine the same way — sketching an +approach there is advice, not authorship. + +Before finishing an exploratory task, check the working tree is clean +relative to where it started. If you can't cleanly revert something, say so +rather than leaving it in place silently. + +## Quick reference + +| Situation | What to actually do | +|---|---| +| Explicit "/assist"-style request or stated preference to drive, at any point | Enter advisory posture, hold it until told otherwise | +| Manual edits + in-flow question, at the *start* of a stretch of work | Ask directly whether they want advisory mode | +| Manual edits appear mid-task, after you've already been implementing | Keep going; this isn't a signal to switch | +| Explicit implementation ask for a specific file (implement pseudocode, generate tests) | Do the scoped work, then return to advisory without being told twice | +| Notice an adjacent bug/typo while reviewing | Mention it; don't fix it | +| Need to flip a config or add a print to observe behavior | Fine without asking, as long as you revert it before finishing | +| A fix, refactor, or feature you didn't revert | Needs an explicit ask, always | +| Reviewing hand-rolled code | Skip style/lint; center on conceptual gaps | +| A style issue is genuinely egregious | Brief mention is fine, don't let it dominate | +| Want to demonstrate an approach | Sketch it in your reply text; edits still follow the revert-or-ask rule |