Sparehand

Docs › The Advisor: learning from mistakes, and what to improve

The Advisor: learning from mistakes, and what to improve

Beta. The Advisor works and is part of the licence, but it is newer than the core and may change between versions. It learns from Crew and Studio, so it has little to say until you use them.

Sparehand's AI features fix their own mistakes as they work: Crew's Master sends a part back and the agent redoes it, Studio's Director fixes a scene the layout check caught, a session's check fails and the next turn repairs it. The Advisor makes sure each fix is made only once: it keeps what was learned as lessons, gives them back next time, and turns what it notices into recommendations for you.

It's in the dashboard, on the Advisor tab, and in the terminal as sparehand advisor. Nothing here costs extra AI usage: the lessons and recommendations come out of calls that happen anyway.

Lessons

A lesson is one sentence about something that went wrong and how to avoid it, kept for one scope:

Where lessons come from, by themselves:

WhenWhat is remembered
The Master reviews a Crew partWhen the part shows something agents keep getting wrong in that repository, or something every brief should say, the review carries a lesson. Most parts teach nothing, so most reviews add none.
The Master's final review of a Crew taskIt looks back at the parts sent back (and why), failed checks, merge conflicts and briefs that were read two ways, and writes what to remember.
The Director checks a video's scenesWhen it fixes scenes the layout check caught and the problem shows a general limit (how much text a scene type holds in that format), it says so.
YouAdd a lesson on the Advisor tab, or sparehand advisor add "LESSON" --repo PATH (--studio, --every-repo).

A lesson that is already remembered (the same words, in the same scope) isn't added twice, and the Master and the Director are shown the existing lessons so they don't repeat them.

Where lessons go, by themselves:

The Advisor tab lists every lesson with where it came from (the task or production, opened with a tap), when, and how often it has been given out. Forget removes one. The Master also recommends moving the stable lessons of a repository into its AGENTS.md once there are five or more: there every tool follows them, Claude Code in the terminal included.

Recommendations

A recommendation is something only you can change. Each one shows once, with where it came from, and comes as a notification on every device that turned notifications on (and from the Mac app). Done marks it taken care of; Dismiss means it isn't raised again. Two sources:

The Master's final review of a Crew task names what would make tasks in that repository go better: a flaky or slow check, a missing test, instructions missing from AGENTS.md (area repository); an agent that didn't fit its parts (agents); how the task was described (the task).

Sparehand's own records, read soon after the dashboard starts, every six hours, and after a Crew task finishes:

It looks atAnd recommends, for example
The last week's jobs, when a quarter or more ran on the hub instead of a worker"myworker was offline when 6 of the last 20 jobs looked for a worker…", "Every worker was busy for 8 of the last 20 jobs…: add a worker, or raise jobs at a time", a worker that is switched off, paused, or short of disk; a checkout that wouldn't copy to a worker
The last 30 days of Crew tasksAn agent whose parts were sent back or failed in 60% or more of its last three or more parts; a repository whose final check keeps failing
Studio's machinesA machine that is on but not set up to render (sparehand studio install NAME)
The voiceWords Whisper didn't hear back more than once, one list per language (add their pronunciation to the brand kit, or keep them as they are)
The lessonsA repository with five or more: put the stable ones in AGENTS.md

A recommendation from the records is raised once and updated in place while the records still show it; when they stop showing it for two days, it is marked done by itself. One you dismissed stays dismissed; one you marked done comes back after a week if the records still show it.

Applying a recommendation

You don't have to make the change yourself. Every open recommendation has:

The brief ends with "if it turns out to be wrong, or already done, say so and change nothing", so a recommendation that no longer holds costs a look, not a change.

Lessons and recommendations about a repository are kept by its path. When you move or rename the repository's folder, tell the Advisor where it went:

sparehand advisor moved ~/code/shop ~/work/shop

Its lessons and recommendations follow it, and so do Crew's tasks in it (git's links to their worktrees are repaired too). Until then, Apply on one of its recommendations says the folder isn't a git repository any more, and the Master doesn't get its lessons in that repository's new place.

From the terminal

sparehand advisor                   # open recommendations, and every lesson by scope (ids on the left)
sparehand advisor list --all        # also the ones you marked done or dismissed
sparehand advisor apply ID          # with Crew when it is about a repository, else in a session
sparehand advisor apply ID --session --repo ~/code/shop   # or choose how, and where
sparehand advisor done ID           # or: dismiss ID, reopen ID
sparehand advisor forget ID         # a lesson
sparehand advisor add "Run the migrations before the API tests." --repo ~/code/shop
sparehand advisor add "Keep bullets scenes to three items." --studio
sparehand advisor review            # look at the records now, instead of waiting for the next look
sparehand advisor moved ~/code/shop ~/work/shop   # a repository moved: its lessons, recommendations and Crew tasks follow it

The dashboard must be running on this computer; the command talks to it on 127.0.0.1.

Files and settings