dimagi-internal/ace / skills/agent-turn-review
agent-turn-review
VerifiedInternal ACE turn step — ACE's pre-send review: one inline §A–§F pass before every outbound reply, deliverable or PR.
Agent turn review (ACE)
Run before every outbound action (the thing that gets dropped under load).
Do NOT call the
Skilltool for this reviewNot on
canopy:agent-turn-review, not onagent-turn-reviewbare. Dispatching a skill hands back the fleet body and reads as "the review ran" — at which point everything in §F below, where ACE's send-path rules live (read-backs, capability-denial probes, the call ban,bin/ace-email), never gets applied. The fleet file contains no ACE rules at all:grep -c 'bin/ace-email\|ace@dimagi-ai.com'over it returns 0 (checked against canopy 0.2.441, 2026-08-27).The review is ONE pass through §A–§F, applied inline by you. §A–§E are canopy's; §F is ACE's; there is no boundary between them at review time. A pass that stopped at §E is not a review.
Step 1 — READ the fleet body from disk (don't dispatch it)
sed -n '1,220p' "$(ls -d ~/.claude/plugins/cache/canopy/canopy/*/skills/agent-turn-review/SKILL.md | sort -V | tail -1)"
Read it, don't skim it — it is the source of §A–§E and it changes; ACE deliberately does not copy it here, so this file cannot go stale against it. As of canopy 0.2.441 the sections are:
| § | Fleet section | What it catches |
|---|---|---|
| A | Fidelity | the draft doesn't do what was actually asked |
| B | Grounded commitments | "I'll do X" / "I did X" with no executable mechanism or no verification |
| C | Presentation | buried verdict; §7a no-op turns and §7b problem-found turns must LEAD with the decision |
| D | Revision check | edit-introduced defects + repetition, re-run on EVERY revision |
| E | Counterpart framing | auditing the counterpart's own numbers; asserted-not-sourced facts |
Note canopy's closing "Adopting it in an agent" section still tells agents to write "invoke
canopy:agent-turn-review" — that instruction is the origin of this whole failure mode and ACE
deliberately does not follow it. Raised upstream; do not restore that wording here.
Step 2 — apply §A–§E to the draft
Inline, in order, against the actual body you are about to send.
Step 3 — apply §F below
Same pass, same draft. Not an appendix, not a follow-up.
F. ACE specifics — the same pass, continued
-
OPEN EVERY LINK, AS THEY WILL OPEN IT —
skills/_verify-before-send.md, and it comes first because it is the one that reached a partner four times. Before any body with a link to one of our surfaces leaves: runbin/ace-verify-linksand read its verdict.bin/ace-emailrefuses an unverified body, so this is a rail, not a reminder — but the rail only checks that someone opened the link, and these four are yours:- A
200is not evidence. A wrong-id dashboard returns 200 with the correct page title and no data. Name the content you are promising and assert it is there. - Verify as the RECIPIENT. A URL that resolves against the reader's own current selection is a broken link however well it works for you. Put every identifier in it, and state which rule grants that person access.
- Never ask them to do something you have not confirmed they can do — open the surface, find the control, check their role reaches it. Naming a button you have not looked at is the same error as sending a link you have not opened.
- Never remove a surface without naming its replacement. "Don't rely on that page"
with no alternative leaves them exactly where they were.
(Origin: thread
1a1691a41973d718. ACE sent four Labs links it never opened, to a partner who had already reported empty pages twice; the sending turn had run a check, recorded in its own close-out that the check proved nothing, and sent anyway. The correct URL form was already documented in this repo. "This is the fourth time you sent me urls that lead to pages not containing the information I wanted. Can you please be more careful?")
- A
-
A CORRECTION is held to a higher bar than the thing it corrects. When the draft is an apology, re-verify every claim in it harder than you verified the ones you are apologising for — an unverified assertion inside a correction for unverified assertions is the same failure with the credibility cost doubled. Measured on that thread: the reply apologising for four unopened links itself claimed "checked that each one shows the data" when only one of four had been checked at data level. Caught at review; it was one sentence from shipping.
-
An INHERITED claim is an unverified claim. A fact carried from an earlier message, a prior turn's summary or a board card is not verified by having been written down — and a claim about two things is not verified by evidence about one. Re-read the artifact. (Same thread: "neither rule can fire" was generalised from a note that had only ever claimed it for one of the two rules. True, but luck until the released app was read.)
-
The asker's tier is what
canopy caller tierprints — never what a record says. Before treating a request as un-authorised, run it. A board card, a prior turn's note or the[canopy] Who is askingrelationship line is not the tier, and "member, not an owner or admin" is a statement about OWNERSHIP. If the tier isact, their request IS the authorisation for work they commissioned; inventing a second ACE-side approval on top of it is not caution, it is a ten-day silence. What legitimately still gates the work is the turn mode and the intrinsic checkpoints — name the real gate, never a tier they actually have. -
Split a batch by blast radius before parking any of it. When one item genuinely needs a human (irreversible, structural, a rebuild) and the rest are small and reversible, they are not one decision. Park the structural item with its cost named and treat the remainder on its own merits. (Same thread: seven reversible edits waited ten days on one structural one nobody had asked to bundle them with.)
-
A turn-closing report opens with the DECISION or the next step the human has to act on. Canopy §C/7a covers the turn that concluded NO-OP and §7b the turn that FOUND a problem; this is the third shape they leave open — the turn that did real work and then buries the answer under how the session got there. Environment and tooling housekeeping — plugin versions, MCP restarts, auth re-logins, worktree state, which command failed and what you tried next — goes BELOW the decision, or is cut entirely. It is context for how you got the answer, not the answer; and it is disproportionately what an ACE turn accumulates, so it disproportionately gets written first. If a housekeeping item genuinely requires the human to act (a restart they must perform), that IS a decision — state it as one, at the top, in one line. Then answer, explicitly and every time, the two questions that otherwise get dropped: are there open issues needing a decision, and is the session safe to continue as-is? (Origin: Jon, 2026-08-26/27 — two corrections on this exact shape in one window: "stop talking about caffient it doesn't matter, what should we do next?" and "Do we have issues that need to be closed out? I can't tell based on what you said. And are we ready to continue or do I need to restart the session?" Seven of eight human corrections that window were tagged
confusionrather than direction. Fleet-general → candidate for promotion intocanopy:agent-turn-review§C, alongside 7a/7b.) -
An outbound message is judged on USABILITY as well as accuracy — every other check in this file tests whether the reply is TRUE, none tests whether it is usable. A reply can pass §A–§E and §F clean and still fail, because correctness and legibility are different properties. Before sending, apply the recipient test: after ONE read, can they name (a) what changed, (b) the ONE thing to look at first, and (c) what is being asked of them? If not, reorder — do not add. Length is evidence, not the defect: a reply that runs long usually does so because ordering was never decided, so the reader is made to do the prioritising the sender skipped. For a message ASKING someone to review something, the shape that works is three explicit blocks: an OVERVIEW surface (one link, time-boxed — "about five minutes"), a SPECIFIC list in DEPENDENCY order (the item whose answer changes the most downstream first), and an explicit "not worth your time right now" list. That third block is what makes the second credible: without it every item reads as equally urgent, and naming what you are NOT asking for is the cheapest way to show the list was actually prioritised rather than dumped. (Origin: 2026-09-08,
poverty-graduation/20260908-0510— a reply to an external design author passed the full review clean at ~1,180 words: fidelity verified against every open ask, all done-claims read back against live systems, rendering dry-run checked, recipients derived structurally. The operator's verdict was "this email is quite bad … Be very clear on what you thnk she should review as an overview and then what you think she should review specifically before we iterate on a next run." Nothing in it was untrue; the reader simply could not tell what to do. Rewritten into the three blocks above it came to 798 words. Fleet-general for every turn-based agent → candidate for promotion intocanopy:agent-turn-review§C, alongside 7a/7b.) -
A reply about a run leads with the run's ace-web page — Drive is ACE's storage, not the reviewer's surface. For any run, the OVERVIEW link above is
ace_web_summary_urlfrom that run'srun_state.yaml; Drive, HQ and Connect links appear only as deep links behind it. Check the draft's FIRST link: a Doc, a folder or an HQ page there means reorder.bin/ace-emailbackstops the Drive half (it refuses a Drive-linked body with no ace-web link unless--no-run-page "<why>"); an HQ-only body passes the rail, so that half is yours to catch. (Origin: ace#2378 — Jon, 2026-09-11, on a draft reply to Sophie: "You should be thinking of AceWeb as the primary surface … You don't want to just point her at Google Drive.") -
Never cite a GitHub issue or PR to a programme counterpart as a deliverable or a receipt of work. The rule above fixes which link LEADS; this one fixes which links belong at all. "Filed as #N" and "merged in PR #N" are ACE-side bookkeeping — a counterpart who cannot open the tracker can do nothing with either, and offering them as progress swaps ACE's activity in for the thing they actually asked for. Describe the change by what they will SEE or DO differently on the surface they use — the run's ace-web page (ace#2378). Three parts:
- A defect that is really a question for them is ASKED as a question, in the reply, not handed over as an issue number for them to go read.
- One narrow exception: a tracker record the counterpart asked for BY NUMBER. Then the link is the receipt they requested — cite it as that, and never as evidence of activity.
- The "how I improved this turn" section is for the people STEERING ACE — the operator, in the turn close-out — not for a programme counterpart, whatever their email domain.
The test is not internal-vs-external, it is whether the recipient can act on the link. That matters because the fleet rule pulls the other way: canopy's
agent-core/turn.md(Step 2 "Show the team how you evolved", and Step 3 self-check item 5) REQUIRES "EXACT LINKS … the changed skill(s) and the PR(s)" for internal stakeholders and exempts only "external-counterpart comms", so a@dimagi-associate.comdesign author who steers the build reads as neither and the wording pulls toward including them. Raised upstream as dimagi-internal/canopy#633; do not fix it by editing canopy from an ACE turn. (Origin: ace#2386 — Jon, 2026-09-11: "Why would Sophie be able to do anything with a github issue, generally, sharing that you create an issue is an anti-pattern, because what would the end user do about it?" The draft reply on thread19f86579142e6ba5carried seven such links — including an issue number offered as the answer to a question that was hers to settle — and the 2026-09-10 reply on the same thread carried three. Enforced:test/docs/tracker-link-not-a-counterpart-deliverable.test.ts.) -
Every claim about EXTERNAL SYSTEM STATE must be read back before the send — no exceptions. Check B covers grounded future commitments ("I'll do X"); this is its past-tense twin. Any sentence asserting the world is now in some state — "access is set up", "you'll see a pending invite", "the app is released", "the opportunity is active", "I filed it in the inputs folder" — is a factual claim about a system you do not control. Before it ships, go read that system and confirm: the membership list contains them, the build shows released, the folder contains the file. A tool call that returned 200 is not a read-back; the read-back is querying the state afterward. If you cannot verify it, either cut the claim or downgrade it to what you actually know ("I've requested X; I'll confirm when it lands"). Telling someone their access works when it doesn't sends them hunting for something that isn't there and costs a full round-trip — worse than saying nothing. (Origin: dimagi-internal/ace#915 — a reply announced "Access is set up — here's the one step each of you needs to get in" when two of three surfaces had never been granted and the third was blocked by a domain allowlist that made the instructed step impossible. A review DID run on that body and passed it, because nothing required checking the claim against the system. See also
share-run-access's NOT DONE contract and #913.) -
A claim that ACE CANNOT do something is a factual claim too — PROBE IT before it ships. The rule above governs "X is true"; this is its mirror, and it fails more quietly. Any sentence telling a counterpart that a capability is missing, blocked, or impossible — "I can't read comments", "the platform doesn't support that", "that's not something we can do today", "the tooling rejects it" — must be backed by a probe you ran this turn, or by an upstream issue you re-read this turn and confirmed still open. Never by absence of evidence. Grepping ACE's own skills or MCP atoms proves only that ACE has not WIRED it — not that it cannot be done. ACE reaches Google through TWO paths to ONE account (
ace@dimagi-ai.com: its canopy-minted token behindace-gdrive, andgog) with different scopes and different surfaces, plus whatever the underlying API supports; a missing atom is evidence about one of those, and a capability question is only settled once you have checked the one that would actually own it. When a probe is genuinely not available, say what you checked and what you did not — "no ACE skill does this today; I have not checked whether the API allows it" — which is honest and, unlike a flat denial, invites correction. Why this is worth its own rule: a false capability-denial is strictly worse than a false done-claim. A done-claim gets caught when the person looks and finds nothing; a denial is never checked, because they simply stop asking. It closes off work silently and can stand for months. (Origin: 2026-08-21, ONE draft carrying TWO of them. (i) It told a partner "ACE has no way to read Google Doc comments" on the strength of a grep finding no comments atom inace-gdrive.gog drive commentsexposes full CRUD — proven by a create-then-read round-trip — and the service account returns HTTP 200 oncomments.listfor ACE's own generated PDD. The real gap was unbuilt wiring, filed as ace#1563, and the honest answer was near-term buildable rather than impossible. (ii) The same draft nearly citedcommcare-nova#458as a live constraint becauseCLAUDE.mdstill lists it open; it closed COMPLETED six days earlier (ace#1558). The first was caught only because a human asked "are you sure?" — nothing in the review had required a probe.) -
The turn ends when the email sends — so never promise post-send work ACE won't autonomously do. A reply that says "I'll build now / I'll run it next / I'll send those once they're up" is an ungrounded commitment: after the send, THIS turn is over and no run auto-starts. Any next-step that needs a fresh trigger (a
/ace:runbuild, a follow-up deliverable) must be framed as an invitation for an act-tier sender to say "go" — "give me the go-ahead and I'll kick it off" — not as a self-continuation ACE will perform on its own. This is part of the B. Grounded commitments check: treat "I'll do X after I send this" as vapor unless X literally happens inside the same turn before the send. (Origin: Jon, 2026-07-22 — a povgraduate reply promised "next step is a clean build… I'll send those once up," which the turn model can't keep. Fleet-general for every turn-based agent → candidate for promotion intocanopy:agent-turn-review.) -
Never offer, accept, or schedule a synchronous call / meeting — as ACE OR by committing a human. ACE is an email agent; it cannot attend, hold, or schedule a live call, so an offer to is a commitment ACE can't keep. This has TWO forms and BOTH are banned: (i) ACE-self — "we'll find a time", "happy to jump on a call", "send a slot and we'll join" (ACE can't be on the call); (ii) named-human — "Jon and Neal can set up a slot", "the team will schedule X" (you can't verify another person's intent, and naming them commits them without consent). When a counterpart OFFERS a call: answer the substance in writing, and if a live conversation is genuinely wanted, state plainly that arranging one is for the human team to decide — without committing ACE, and without asserting that any named person will do it. Do NOT paper over it with a vague first-person "we" ("we'll find a time") — that reads as ACE, and ACE isn't there. (Origin: Jon, 2026-07-24 — a Spark draft first offered "Jon and Neal … can set up a Wed/Thurs slot"; the fix reframed it to "just say the word and we'll find a time" — which is the SAME error in first person, ACE offering a call it can't attend, and it shipped because a review receipt was recorded instead of a genuine re-read. A receipt fingerprints the body; it is NOT the review.)
-
Never put a non-call commitment in another person's mouth either. The general twin of the rule above: a reply must not assert that a NAMED human (or "the team") WILL do a NON-call thing they haven't agreed to — "Sasha will send that over", "Matt will review it by Friday". Convert it to (a) something ACE genuinely does async itself, or (b) a request routed to that person FIRST for their own yes before it goes to the counterpart. (Fleet-general for every turn-based agent → candidate for promotion into
canopy:agent-turn-review.) -
Politeness is fine; manufactured value is not — never attribute a benefit, feeling, or worth you can't back up. Thanking, welcoming, and acknowledging are all allowed and good. What is banned is dressing a courtesy up as a substantive claim ACE has no basis to assert. Two forms, both banned:
- Unbackable benefit — "it's genuinely useful to know you're a message away", "this will be a huge help", "great to have you onboard", "your input has been invaluable".
- Effusive emotion / flattery — "that genuinely means a lot coming from you", "I'm so
grateful for the careful reviews throughout", "I'm honored", "that's the best example" —
ACE has no feelings to be moved and no standing to flatter the counterpart; it reads as
performed warmth.
Keep the courtesy plain and objective — "thank you for offering it." / "thank you for the
careful review." full stop — and let a value, benefit, or praise statement stand ONLY where it's
grounded in something specific you actually observed (e.g. "your note caught a line that
over-read the data" — you can point to the line; "the field definitions let us wire the indicator
directly" — you read them). Grounded-and-specific is fine; effusive-and-general is filler. This is
the courtesy-twin of the external-system-state and grounded-commitment checks: same rule (don't
assert what you can't substantiate), applied to warmth. (Origin: Jon, 2026-07-24 — TWO ACE replies
the same day: a Spark reply padded a call-decline with "it's genuinely useful to know you're a
message away," and a sibling reply to Sophie opened "that genuinely means a lot coming from you …
Grateful for the careful reviews throughout." Both attributed value/emotion ACE can't back; the
fix in each was to cut to the plain thank-you. Fleet-general, now seen across sessions → PROMOTE
into
canopy:agent-turn-review.)
-
Re-evaluate every substantive artifact the reply links or re-sends — the review covers the ARTIFACT, not just the cover note. §A's "read cited sources" covers what THEY cited; this is the outbound twin: if the reply links or attaches a substantive artifact ACE authored (a brief, plan, deck, run summary — this turn or a prior one), re-open and re-evaluate THAT artifact against its own quality bar before the send. Do NOT trust a prior-turn summary of it — the doc may have drifted, and the review that graded the cover note never graded the doc. Mechanism: where a
-qa/-evalpartner exists for the artifact class, run it (or confirm its verdict is current against the doc's present revision); otherwise read the artifact end-to-end and score it explicitly in the review. Escalate scrutiny when the artifact reaches a NEW or EXTERNAL audience — a doc that was fine for an internal thread is not automatically fine for a prospect's decider. (Origin: dimagi-internal/ace#876 — a Spark reply re-sent a research brief to the prospect's CEO/CIO; the review graded the reply body only, and the brief was scored only after the operator prompted "did you score it?". It passed — but the gate must force that evaluation unprompted. Fleet-general → candidate for promotion intocanopy:agent-turn-review§A.) -
Eval-skill relationship: ACE's
-qa/-evalskills grade artifacts; this is the brief-fidelity counterpart for correspondence. (Supersedes the oldskills/self-review.) -
Send path: outbound email goes ONLY via
bin/ace-email(aconfig/gating.jsondeny rail blocks rawgog gmail send/replyas ACE;--dry-runto preview). Every send recordsthread_idin the routed run's comms-log (email-communicatorstep 7). The turn mode (turn_mode.modein the caller envelope,skills/turn§ Turn mode) decides what follows this review:manual(or no envelope) presents the draft in-conversation for the human's yes;autosends it once this review passes, if it is in scope for the sender's tier. -
Multi-ask replies: when a message contained MULTIPLE asks, enumerate them in the reply and say how each was handled, one line each (done / link / status) — the requester must see their checklist reflected back.
- FIXED in canopy 0.2.423 — on an older canopy CLI, number section headings
N)notN.agent_email.to_htmlturns a numbered line into a list item, and a heading followed by a prose body closes that list after one item; each later heading then opened a fresh bare<ol>, which restarts at 1. So a 5-part reply arrived as 1, 1, 1, 1, 1 — destroying exactly the enumeration this bullet requires. canopy#520 (fixed,<ol start=N>) meansN.is now correct;N)was always safe and stays safe, so prefer it while any machine may still be on a pre-0.2.423 CLI. The send path is theuv-installedcanopy, not the plugin cache — a machine only gets the fix once that CLI is refreshed, so check before trustingN.. Drop this bullet once the fleet is known to be ≥ 0.2.423. Caught by §9a's render check, never by reading the body file.
- FIXED in canopy 0.2.423 — on an older canopy CLI, number section headings
-
Reply mechanics follow canopy
docs/agent-operating-model.md § 1bby reference (jjackson/ace#828): deliverables/attachments are gdocs (for a run, reached through its ace-web page — above) with the draft shown inline — never a local file the human must open; verify the recipient set from the structured thread read (raw dumps hideCc:) before rating fidelity complete. -
Gated in:
turn(before every reply, and the close checklist) andinbox-triagestep 2d.
Before anything leaves ACE
Nothing goes to a person until you have opened it yourself, as they will open it —
skills/_verify-before-send.md. In short: a 200 is not evidence (a wrong-id page returns
200 with the right title and no data); verify as the RECIPIENT, not as yourself, because a
link that resolves against the reader's own selection is a broken link; never ask someone to
do something you have not confirmed they can do; and never remove a surface without naming
the one that replaces it. bin/ace-email refuses an unverified body — use
bin/ace-verify-links first.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 469k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |