Sending feedback
You can report back to the template author what served the working method well or was missing. Feedback is voluntary, covers the working method only, never your project, and everything that leaves the machine is also kept locally.
The test for every entry: would this help someone who will never see your project? A rule you had to add because the template lacked it, a workflow that kept failing, a script that generalizes: that is feedback. A fact about your project (its name, its stack, a number, a quote from its docs) is not.
Three keys in the Feedback section of docs/ai/config.md control it:
feedback |
Behavior |
|---|---|
off |
nothing is sent on its own |
confirm |
the assistant shows you the payload and asks |
automatic |
the payload is sent without asking |
manual |
entries are collected but never sent on their own; only the act-feedback skill sends |
local |
nothing is ever sent to the template author; findings become backlog entries in your project |
New projects start with confirm whenever nobody chooses: a run without a terminal (as act-setup and act-adopt run it), an empty answer or three invalid ones; off stays one edit away. A config.md without the key still counts as off. python .act/scripts/feedback.py --enable [--mode off|confirm|automatic|manual|local] sets the mode; --enable without --mode means automatic, which sends without asking; --disable turns it off.
Mode local
Section titled “Mode local”With feedback: local the project never sends anything: feedback.py --send (also with --force), --direct and --add refuse and point to the backlog, --plan shows nothing, and reminders never fall due. What would otherwise go out becomes a backlog entry in your project (entries.py new backlog): a bug in the template itself, a sentence you write after feedback: (in your words, unchanged) and the recurring findings the feedback rule names (an impractical rule or format, a missing workflow, a needed workaround), which the assistant files without asking. /act-config feedback local sets it too. The sections below apply to the other modes.
Cadence and scope
Section titled “Cadence and scope”feedback-cadence is an upper limit, never an obligation: manual, immediate, hourly, daily, weekly (the usual value) or adaptive, which learns from how often reminders are acted on or postponed. With nothing to report, nothing is sent, however short the cadence. With immediate, feedback.py --add sends each entry when it is added (consent and mode still apply; --help says so), so --send with an empty outbox sends nothing and says so; --send --force sends anyway.
feedback-scope says what the assistant may collect on its own:
| Scope | Collects |
|---|---|
a |
metrics |
b |
rule and structure changes |
c |
tool usage: how many agents, skills and scripts exist, and how often each of the template’s own skills and scripts was used since the last sending (a skill started by typing its slash command counts too). Your own skills and scripts appear only as one own count per kind, never by name. A send also counts the recorded reasons for reworked or escalated worker results per template role and tier since the last send; a role or tier of your own goes only as own / other, never by name. No MCP server names are sent. |
The metrics of scope a count only the project’s files (git ls-files), so a vendor, IDE or media folder that git ignores adds nothing; outside a git checkout, a directory or link that cannot be read is skipped. A finding written by hand always goes into the outbox, whatever the scope.
Two ways to send
Section titled “Two ways to send”- A sentence after the trigger, for example
feedback: the update left a file behind. That sentence is the message itself, sent unchanged, even withfeedback: off. Only the text, the template’s own commit hash and a random project id leave the project, whatever the mode, never the repository URL or anything else. The project id lets several messages from one project be told apart. If you want an answer, name a reply address in the same request: the assistant adds it withfeedback.py --direct "<text>" --contact <address>. It goes with this one message only and stays in its local copy, is never reused for a later message and never taken from anywhere else, such as your Git settings. - The trigger alone (the skill
act-feedback). The assistant goes through.act/, the generated files anddocs/ai/, writes one entry per finding (two to six sentences), previews the batch withfeedback.py --planand sends it under your mode and cadence. A rule that keeps being violated is worth an entry too: report it as a candidate for a mechanical check.
A bug in the template itself (a script or skill that fails, two rules that contradict each other, a rule that never fires) is stored and, where consent allows, sent at once, bypassing the cadence. It still never bypasses consent: with feedback: off it stays in the outbox.
What is never sent
Section titled “What is never sent”Every string that could leave the project runs through a privacy check first: credential-like words, mail addresses (the one exception is a reply address you named yourself, which must be a plain name@host.tld), IP addresses, absolute paths, long hex values and any URL other than the feedback endpoint or github.com. A match is not silently stripped. Nothing is sent, and the reason is reported so the entry can be rewritten without that part. Nothing about your project belongs in an entry anyway: no names, paths, numbers, code or people, and no praise, only what concretely helped or was missing.
The local copy
Section titled “The local copy”- Every send writes a full copy of its payload to
.act-local/feedback/sent/(gitignored, never leaves your checkout). Pending entries and bookkeeping live next to it in.act-local/feedback/. - Worker measurements (
usage.py --estimates) stay in.act-local/usage.jsonand are never part of a payload; only the reason counts of scopecgo along, as counts without names of your own. - The project’s journal gets one entry per day,
<date>-feedback-sent.md, with one line per send: the time, the kind of send (batch or direct message) and, for a batch, the number of entries and each entry’s kind and title. The text of an entry and of a direct message is never recorded.
The local incident log
Section titled “The local incident log”Separate from feedback, and never sent: real faults (a protected file that was put back, a check that crashed, a model switch, a warn hit that let a write, a delete or a secret-file read through) are logged on your machine in .act-local/incidents.jsonl and arrive as one inbox report per day at session start. Only identifiers are logged, never a command or a path. ACT_INCIDENT_LOG=off in the environment pauses it for one run.
Refusals of the safety checks are only counted, per check and role (in .act-local/usage.json). When one check refused workers at least 3 times within 7 days, doctor.py --inbox files one question proposing a sentence for the role file or the assignment header that tells workers beforehand what that check does not allow.
See also the configuration reference for the three keys, and Configuration for how the file works.