cocottetech/@platform/codebase/@features/ai-copilot/docs/audit-to-counter-action.flow.md

Flow — audit row → counter-action

Goal

Make it natural for Quinn to discover a past action she's unhappy with and either teach the system (lightweight: 👎 + correction pattern) or counter the action (heavyweight: schedule a retraction / apology / revert). Brief I introduced the affordances; this flow shows the path step-by-step.

Constraints

• agent_actions rows are append-only. Counter-actions are themselves new rows, threaded by target_id.
• Some external effects can't be undone (a DM sent is sent); the flow surfaces that honestly.
• Counter-actions emit their own approval card if stakes are medium+, even for users who set the original to auto.

Flow

Step 1 — Entry point

Quinn opens the audit drawer (brief B4 / I2). Filters down to the action she's curious about. Taps the row → row detail sheet (brief I3).

Step 2 — Row detail

Sheet shows:

• Header: specialist badge + action_type + target preview + stakes dot + auto/approved indicator + timestamp.
• "Why" panel: confidence + the policy that allowed it.
• Outcome panel: human-readable rendering of outcome_json (success payload or failure trace).
• Before/after diff (if applicable — profile edits, plan changes).
• Affordance row at bottom:
  • 👍 / 👎 (teach)
  • Counter-action ▾ menu (the path this flow follows)
  • Close

Step 3 — Counter-action menu opens

The menu's contents are derived from the row's target_kind and action_type — there's no generic "undo" because the right counter depends on what was done:

Original action	Counter-action options
publish_post	retract_post (delete from platform) · edit_post · add_correction_reply
send_dm	send_followup_dm (apology / retraction) · (no true undo — DM is sent)
update_profile	revert_to_previous · edit_profile
bump_availability	pause_bumps (toggle H1 policy)
set_ppv_price	change_price
update_availability (directory)	mark_unavailable · edit_listing

Step 4 — Selecting a counter-action

• Reversible kinds (retract_post, revert_to_previous, pause_bumps) → direct confirmation card.
• Irreversible kinds (send_followup_dm) → confirmation dialog with explicit text: "The original DM is already sent — this adds a follow-up. Continue?" Quinn taps Confirm (or types "yes" if the DM is high-stakes).

Step 5 — Counter-action approval card

Same approval-card shape as brief A. Differences:

• Title prefix: "Counter: ..."
• Footer line: "Counters action <original_id> (tap to view in audit drawer)."
• Stakes: inherits at least the original stakes (counter-action of high-stakes original is also high-stakes).

Step 6 — Dispatch + thread

• Quinn approves → counter-action dispatches through the right @ai/@skills/platform-*/actions/*.
• A new agent_actions row is created with target_id linking to the original.
• The audit drawer now shows the original row with a small "counter-action thread (1)" badge.
• Tapping the badge expands the original → shows the counter row inline beneath it.

Step 7 — Learning hook

When a counter-action lands, ai-copilot may proactively suggest a policy adjustment:

• "You countered 3 of content-x's DMs this week. Want me to require approval on all of its DMs for the next week while it recalibrates?"
• That suggestion is itself an approval card (brief I5 — policy graduations, in reverse).

States to design

• Row detail with counter-action menu collapsed / expanded.
• Counter-action approval card.
• Irreversible-action confirmation dialog.
• Audit row with counter-thread badge.
• Audit row expanded showing thread.
• "Recommend tightening this specialist" proactive card.

Out of scope

• Bulk counter-actions ("counter all DMs from last hour") — wait for evidence it's needed.
• Time-travel "what if I had countered this 3 days ago?" — fun but not P0.

Open questions

• Should counter-action irreversibility be visually distinct from normal stakes-high (e.g. a one-way arrow glyph)?
• The "thread" badge — number, dot, or chip? Test on dense audit drawers.
• When 3+ counters land on the same specialist in 24h, auto-pause that specialist's auto-actions instead of just suggesting it?