Actions and follow-up

An action turns what your results show into owned follow-through: a named person, a metric to move, a date to look again, and later a record of what actually changed. Pencil keeps the record. People decide what to do and whether it worked.

An action starts from a recommendation: one an operator writes by hand, linked to the results it rests on, or the recommendation of an analysis, which an operator turns into an action and edits as their own. Either way a person owns it and decides whether it worked.

Create an action

There are two ways in:

• On a flow's Results page, choose Turn this into an action under a question, or Turn these results into an action for the whole revision.
• Open Actions in the navigation and choose New action, then pick the flow, the published revision and, if you want, one question.

Fill in:

• Title and Rationale: the recommendation, in your own words.
• Owner: one of your workspace's operators.
• Review date: the day to look again, in the workspace time zone.
• Target metric: its name, its unit (such as percent), whether higher or lower is better, the baseline value, where the baseline came from, and when it was observed.

Do not paste respondent answers or names into the rationale. If you later create an external task, the rationale is sent with it.

Saving an action contacts no one. Nothing leaves your deployment until you confirm an external task, described below.

What the action keeps as evidence

When you save, Pencil copies the counts the results page showed at that moment: the revision's completed responses and starts, and for a question, how many sessions reached it, how many answered, and the count for each option with the number of answers it is out of. These figures stay as they were, so the action keeps its evidence when later responses change the results.

An action never stores response IDs, answer text or excerpts, typed numbers or dates, or a filter that picks out a small group. That keeps actions out of response and contact erasure entirely: erasing a respondent never needs to touch an action, and an action never points back at a person. Counts are copied only as the whole revision shows them, never for a filtered group.

The lifecycle

A new action is Planned. It moves only along these steps, and Pencil refuses anything else:

Every move records who made it, when, and an optional note. Changes to the title, rationale, owner, metric or review date are recorded in the same history. An action that is Effective, Ineffective or Closed can no longer be edited, so its measured record stays as it was reviewed. A closed action stays closed.

Measure, then decide

When the review comes round, open the action and record an observed value under Follow-up measurement: pick the later flow, and optionally the revision, enter the value and when it was observed. It must use the same unit as the baseline; a different unit is refused so the two stay comparable. Pencil then shows the difference from the baseline and whether it moved in the direction you wanted.

From Ready for review, you mark the outcome Effective or Ineffective. That verdict is yours. Pencil never sets or changes it: no scheduled job, setting or extension writes it, and recording a measurement does not decide it.

When the review date arrives, the action shows Review due on the Actions page, on the action itself and on the flow dashboard, until it gets a verdict or is closed. Nothing else happens: Pencil does not move, close or judge the action for you.

External tasks

You can send an action to your own task system as a task. This is optional. Without it, everything above works.

Turn it on

Pencil includes one adapter that needs no vendor account: a webhook to a receiver you run. Set these on your deployment, all as Worker secrets so a later deploy keeps them:

Until all three are set, Create external task is disabled and says what to set.

What leaves, and when

Choosing Create external task shows the confirmation screen: the exact JSON that will be sent, and nothing else. It holds the action's title, rationale, owner name and email, metric with its baseline, review date, and a link to the action in Pencil that needs an operator sign-in to open. Raw answers, excerpts and evidence figures are never included. Only after you choose Confirm and send does anything leave, and only those confirmed values.

If the action changes after you confirmed and before the task is delivered, Pencil refuses to send the old confirmation and asks you to review and confirm again.

The webhook contract

Pencil sends one POST to TASK_WEBHOOK_URL:

• Authorization: Bearer <TASK_API_KEY>. The key is sent only in this header. It is never written to the database, an audit entry, a log line or an export.
• Idempotency-Key: pencil-action-<action ID>. The same key is in the body as idempotencyKey. One action has one key for its whole life.
• Content-Type: application/json, with this body:

{
  "idempotencyKey": "pencil-action-01J…",
  "action": {
    "title": "Shorten the wait at the counter",
    "rationale": "Most visitors said the wait was too long.",
    "owner": { "name": "Sam Rivera", "email": "sam@example.com" },
    "metric": { "name": "Visitors saying the wait was short", "unit": "percent", "direction": "increase", "baseline": { "value": 33, "source": "Revision 1 results", "observedAt": "2026-10-12T09:00:00.000Z" } },
    "reviewDate": "2026-12-01",
    "reportLink": "https://forms.example.com/app/actions/01J…"
  }
}

Your receiver must honour this contract:

• Create or get by key. The first request with a key creates one task. Every later request with the same key returns that same task and creates nothing.
• Answer 2xx with {"taskId": "<your task ID>"}. The ID is 1 to 200 visible ASCII characters. Pencil reads nothing else from the answer.
• Do not redirect. Pencil does not follow redirects; a 3xx counts as failed.

Delivery states

Pencil records every attempt before it is made: when, by whom, the outcome and its class, the HTTP status, and the remote task ID when there is one. Nothing else from the answer is kept. Pencil never retries on its own, and never sends again under a new key.

Backup and restore

Actions, their history, evidence figures, measurements, task deliveries and every attempt are part of the deployment export and come back exactly as they were. The task key is never in an export. Restoring sends nothing: a delivery that was Unknown is still Unknown after restore, and nothing is sent until an operator chooses retry. See Backup and restore.