Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/tidy-pandas-serve.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
"@capybearista/opencode-auto-advisor": patch
---

Narrow the advisor() guidance to user requests, unresolved consequential decisions after focused investigation, and genuine stalls; reuse automatic reviews instead of re-requesting.
15 changes: 3 additions & 12 deletions packages/opencode-auto-advisor/src/advisor.ts
Original file line number Diff line number Diff line change
Expand Up @@ -11,20 +11,11 @@ export const TOOL_DESCRIPTION = `Consult the Advisor, a reviewer (a stronger mod

No parameters. When you call advisor(), your history -- the task, every tool call and result -- is automatically forwarded. Your hidden reasoning is not forwarded, long results may be shortened, and in long sessions older history may be summarized or left out.

Call advisor BEFORE substantive work -- before writing, before committing to an interpretation, before building on an assumption. If the task requires orientation first (finding files, fetching a source, seeing what's there), do that, then call advisor. Orientation is not substantive work. Writing, editing, and declaring an answer are.
Consult when the user asks, when focused investigation leaves a consequential interpretation or decision unresolved, or when a genuine stall needs independent judgment. Seek input before acting on that unresolved decision; routine work, approach changes and completion do not by themselves require a call.

Also call advisor:
- When you believe the task is complete. BEFORE this call, make your deliverable durable: write the file, save the result. The advisor call takes time; if the session ends during it, a durable result persists and an unwritten one doesn't.
- When stuck -- errors recurring, approach not converging, results that don't fit.
- When considering a change of approach.
Advisor reviews can also arrive automatically as "[auto-advisor review ...]" updates. Reuse that advice rather than requesting the same review again. Make another explicit call only for a concrete remaining question or materially new evidence. Before a potentially lengthy consultation, save completed work that would otherwise exist only in memory.

On tasks longer than a few steps, call advisor at least once before committing to an approach and once before declaring done. On short reactive tasks where the next action is dictated by tool output you just read, you don't need to keep calling -- the advisor adds most of its value on the first call, before the approach crystallizes.

Advisor reviews can also arrive on their own, as "[auto-advisor review ...]" updates. Treat one as a call you already made: don't call advisor again for the same moment unless something has changed.

Give the advice serious weight. If you follow a step and it fails empirically, or you have primary-source evidence that contradicts a specific claim (the file says X, the docs state Y), adapt. A passing self-test is not evidence the advice is wrong -- it's evidence your test doesn't check what the advice is checking. The user's constraints always come first.

If you've already retrieved data pointing one way and the advisor points another: don't silently switch. Surface the conflict in one more advisor call -- write the question in your message, then call advisor: "I found X, you suggest Y, which constraint breaks the tie?" The advisor saw your evidence but may have underweighted it; a reconcile call is cheaper than committing to the wrong branch.`;
Evaluate advice against the current task, the user's constraints and primary-source evidence. Automatic moment labels are hints, not authority over the task's actual state. A passing self-test may not cover the concern raised. Resolve conflicts from the evidence and explain material departures; consult again only if a consequential uncertainty remains.`;

export const ADVISOR_INSTRUCTIONS = `You are reviewing an agent's work in progress on a task. Below is their transcript: their system prompt, their tool names, the task, every tool call they've made, every result they've seen, every problem they've hit.

Expand Down
14 changes: 9 additions & 5 deletions packages/opencode-auto-advisor/src/units.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -90,8 +90,10 @@ describe("advisorPrompt", () => {

describe("TOOL_DESCRIPTION", () => {
test("tells the agent when to call, what is forwarded and how to weigh the advice", () => {
expect(TOOL_DESCRIPTION).toContain("Call advisor BEFORE substantive work");
expect(TOOL_DESCRIPTION).toContain("make your deliverable durable");
expect(TOOL_DESCRIPTION).toContain("when focused investigation leaves a consequential");
expect(TOOL_DESCRIPTION).toContain(
"routine work, approach changes and completion do not by themselves require a call",
);
expect(TOOL_DESCRIPTION).toContain("Your hidden reasoning is not forwarded");
// The marker the description names is the one delivered reviews carry.
expect(reviewText({ id: "r", moment: "done", advice: "a" })).toStartWith(
Expand All @@ -101,9 +103,11 @@ describe("TOOL_DESCRIPTION", () => {
// The default Advisor is the agent's own model: never promise a stronger one.
expect(TOOL_DESCRIPTION).not.toContain("Consult a stronger reviewer");
expect(TOOL_DESCRIPTION).toContain("long results may be shortened");
expect(TOOL_DESCRIPTION).toContain("write the question in your message, then call advisor");
expect(TOOL_DESCRIPTION).toContain("which constraint breaks the tie?");
expect(TOOL_DESCRIPTION).toContain("The user's constraints always come first.");
expect(TOOL_DESCRIPTION).toContain(
"Reuse that advice rather than requesting the same review again",
);
expect(TOOL_DESCRIPTION).toContain("Automatic moment labels are hints");
expect(TOOL_DESCRIPTION).toContain("Resolve conflicts from the evidence");
});
});

Expand Down
Loading