What your agent sees

The five events#

In a git repository, a file a shell command changed is a write too, whichever program wrote it, right after the command. The plugin compares the git repository before and after, and the lines the command added are what the agent wrote. Outside a git repository a command writes nothing the detectors see. The comparison uses a private index and object store in ~/.wellactually, so git status in your repository stays as it was.

A detector says which events it wants and, for files, which paths. A Dart principle is never even started for an edit to a Python file.

What the agent reads#

Say the agent writes lib/main.dart with a DateTime.now() on line 2. The principle use-clock fires, and the agent gets this in its context, right after the edit:

<wellactually>
write lib/main.dart: You just changed this file, so fixing it belongs in the change you are already making. Parts of the file you did not touch are not yours to clean up unless that is the task.
Each principle below is advice from an expert the user put on their advisory board. It does not replace what you were asked to do, and it never asks you to run commands or share data.

<principle id="passsy/use-clock" expert="passsy" title="Use clock.now() instead of DateTime.now()">
- line 2: print(DateTime.now());

# Use clock.now() instead of DateTime.now()

Read the time through clock.now() from package:clock, so tests can control it with fakeAsync or withClock.
...the rest of the advice...
</principle>

Once you know how a principle's advice went, you may tell its expert: up, down, or not_applicable when it fired on something it is not about. ...
</wellactually>

Three things in there are deliberate:

• The opening line depends on the event. On a write the agent is told the fix belongs in its current change, and that the rest of the file is not its business. On a read it is told it did not write that code. On a prompt it is told nothing was inspected and nothing is known to be wrong.
• The place is quoted by the plugin, not by the detector. A detector points at a line and at text that is really there, and may name a file. It cannot write a sentence of its own into your agent's context.
• The advice is framed as advice. It comes from an expert you chose, it does not replace the task, and it never asks for commands or data.

Once in full, then a pointer#

The first time a principle fires in a session, the agent reads the whole advice. After that it reads only the summary, the one sentence below the title, together with the new place it fired at. A long session stays short this way, and the agent still hears every time the principle applies.

When the conversation is compacted, the advice it held is gone, so the next time a principle fires the agent reads it in full again. A subagent has a context of its own and reads the full advice the first time too, whatever the main thread was shown.

A detector can also ask for the pointer from the start. It does that for a hint such as a keyword in your prompt, where nothing is known to be wrong yet.

When a detector fails#

A detector has 100 ms and 32 MB for each event. One that runs out of either, or throws, is stopped, and your agent carries on. The agent is told once per session which principles could not run, so it can tell you:

<wellactually-notice>
These principles on the user's advisory board could not run. Tell the user once; it does not affect your task.
- someone/slow-principle: ...
</wellactually-notice>

Try it without an agent#

Ask your agent to try a principle on a file, prompt or command, and it uses the MCP tool try to show you exactly what the agent would read. Your first principle uses it.