Start at the crux.

From an idea to a prepared meeting

This walkthrough follows an organizer who says, “We need to choose an analytics vendor Thursday.” There is no JSON file to understand first. The organizer explains the meeting in ordinary language, and Treffen records just enough structure to design useful pre-work.

For readability, the page renders routine command results in their human form and expands JSON only when the artifact boundary matters. In automated use, Treffen emits versioned JSON by default.

Before you begin

Install Treffen and EDSL together so the treffen and ep commands use the same managed environment.

$ uv tool install --upgrade --force \
  --with-executables-from "edsl @ git+https://github.com/expectedparrot/edsl.git@main" \
  "treffen[fielding] @ git+https://github.com/expectedparrot/treffen.git@main"

Humanize collection requires an Expected Parrot account. Check authentication without displaying the API key.

$ ep auth status

Authenticated with Expected Parrot

If authentication is missing, run ep auth login. The CLI handles the credential; it should not be pasted into a prompt, terminal transcript, or repository.

1. Start a meeting workspace

Create a directory for the meeting. The title and date provide orientation without requiring a formal meeting charter.

$ treffen init vendor-decision \
  --title "Analytics vendor discussion" \
  --scheduled-at "2026-08-13T14:00:00-04:00"

Created meeting workspace: vendor-decision
Title: Analytics vendor discussion
Scheduled: Thursday, August 13 at 2:00 PM
Next: explain what this meeting is for.

The directory is the durable home for the meeting. Treffen keeps its internal history under .treffen/ and places deliberate exports elsewhere.

2. Explain the purpose and information need

The organizer does not need a formal decision charter. A useful description of the purpose and the information needed from participants is enough.

$ treffen -C vendor-decision outcome set \
  --text "We need to choose among Buildly, MetricFlow, and an internal build. Before Thursday I need to know what each person prefers, what tradeoffs drive that preference, and whether the migration estimates actually differ."

Purpose recorded.
Information needed:
  • current preference and fallback
  • importance of speed, control, cost, and vendor risk
  • migration estimate and assumptions
Next: add useful context and participants.

Treffen—or the coding agent driving it—can clarify this statement conversationally. The aim is to understand what participant input would improve the meeting, not to demand ceremonial fields such as a named decision owner.

Add facts or suspicions only when they will help shape the questions. Each command records one idea and can be corrected independently.

$ treffen -C vendor-decision context add --kind history \
  --text "The team has postponed this choice twice."

Added context C01 · history
The team has postponed this choice twice.

$ treffen -C vendor-decision context add --kind hypothesis \
  --text "Alice and Chen may disagree about migration effort."

Added context C02 · hypothesis
Alice and Chen may disagree about migration effort.

3. Add the people whose input matters

A participant needs a stable ID and a name. Role and expected attendance are useful context, but email is optional. Add people even when they may not attend if their information should shape the meeting.

$ treffen -C vendor-decision participant add alice \
  --name "Alice Wu" --role "Engineering lead" --attendance expected

Added Alice Wu (alice)
Role: Engineering lead
Attendance before the meeting: expected

Repeat this for Priya, Chen, and Marco. Marco is marked not_expected, but his finance constraints are still worth collecting.

Treffen can now propose a light-touch collection plan from the purpose, information needs, context, and roster.

$ treffen -C vendor-decision plan propose

Proposed pre-work:
  • a survey under five minutes for all four participants
  • an adaptive follow-up for Alice and Chen on migration estimates
  • collect Marco's finance perspective even though he is not expected to attend
Next: design and review the questions.

4. Turn the information need into a survey

The decision template chooses question types for their measurement properties. It does not turn every input into prose. In this meeting, the organizer needs an ordering of options, a forced tradeoff among decision criteria, a confidence measure, bounded risk selection, and comparable factual estimates.

The table is a design menu, not a checklist. This meeting only needs questions that answer the organizer's stated information need. We will build the short structured survey one question at a time so each design choice is visible.

$ treffen -C vendor-decision question add decision-core \
  --id option-ranking --type rank --required --num-selections 3 \
  --option Buildly --option MetricFlow --option "Internal build" \
  --text "Rank the three options from most to least preferred." \
  --purpose "Measure the complete ordering, including the fallback."

Added question option-ranking to decision-core
Type: rank · required · ranks all 3 options

$ treffen -C vendor-decision question add decision-core \
  --id criterion-allocation --type budget --required --budget-sum 100 \
  --option "Implementation speed" --option "Data control" \
  --option "Year-one cost" --option "Vendor risk" \
  --text "Allocate 100 points according to how much each criterion should matter." \
  --purpose "Force an explicit decision-criteria tradeoff."

Added question criterion-allocation to decision-core
Type: budget · required · total must equal 100

$ treffen -C vendor-decision question add decision-core \
  --id ranking-confidence --type linear_scale --required \
  --option 0 --option 1 --option 2 --option 3 --option 4 --option 5 \
  --option 6 --option 7 --option 8 --option 9 --option 10 \
  --option-label "0=Very tentative" --option-label "10=Very confident" \
  --text "How confident are you in that ranking?"

$ treffen -C vendor-decision question add decision-core \
  --id missing-information --type yes_no --required \
  --text "Is critical information missing from the current decision packet?"

$ treffen -C vendor-decision question add decision-core \
  --id information-needed --type free_text \
  --text "What missing information would most improve this discussion?"

$ treffen -C vendor-decision instrument skip add decision-core \
  --question information-needed \
  --when "{{ missing_information.answer }} == 'No'"

treffen -C vendor-decision question add migration-interview \
  --id migration --type interview --required --max-turns 8 \
  --text "Develop a defensible migration estimate and identify its assumptions." \
  --interview-guide "Elicit a best estimate in weeks; ask for phases, staffing, \
dependencies, evidence, the largest uncertainty, and what would falsify the estimate. \
Do not argue for a vendor. Ask a numerical estimate and a confidence category before ending." \
  --purpose "Test the suspected factual disagreement without losing comparable fields."

treffen -C vendor-decision instrument interview configure migration-interview migration \
  --mode text --interviewer-name "Treffen research partner" \
  --checklist migration-checklist.json \
  --structured-question numerical \
  --structured-question multiple_choice \
  --end-policy interviewer_gated \
  --lock-after-complete

What a participant sees

The construction details compile into a short survey. The participant sees ordinary questions, not EDSL class names or CLI options.

Analytics vendor meeting prep

1. Rank the three options from most to least preferred.
   Buildly · MetricFlow · Internal build

2. Allocate 100 points according to how much each criterion should matter.
   Implementation speed · Data control · Year-one cost · Vendor risk

3. How confident are you in that ranking?
   0 — Very tentative                         10 — Very confident

4. Is critical information missing from the current decision packet?
   Yes · No

5. [Shown only after Yes] What missing information would most improve
   this discussion?

Alice and Chen also receive a bounded adaptive interview. It follows their answers instead of asking both people an identical list of open-text questions.

Treffen research partner: What is your best estimate of the migration time?

Alice: About two weeks if the event schema is already stable.

Treffen research partner: Which dependency makes that estimate most fragile?

Alice: Identity mapping. If historical IDs need reconciliation, add at least
another week.

5. Review and send the pre-work

First inspect a concise survey summary. This checks the question count, types, branching, and expected burden.

$ treffen -C vendor-decision instrument show decision-core --format summary

decision-core: 5 questions · 1 skip rule
Types: rank, budget, linear_scale, yes_no, free_text
Estimated median completion time: 3m 40s

Inspect the interview separately because it has different participants, burden, and completion rules.

$ treffen -C vendor-decision instrument show migration-interview --format summary

migration-interview: 1 adaptive interview · maximum 8 turns
Participants: Alice, Chen
Checklist items: 8 · structured question types: numerical, multiple_choice
Estimated median completion time: 8m 30s

Next, preview the participant experience and build the EDSL artifacts. The preview is the point to revise confusing wording or remove unnecessary questions.

$ treffen -C vendor-decision instrument preview decision-core

$ treffen -C vendor-decision collection build

{
  "status": "ok",
  "data": {
    "build_id": "col_01",
    "plan_revision": "sha256:91c…",
    "deployments": [
      {"instrument": "decision-core", "participants": 4, "questions": 5},
      {"instrument": "migration-interview", "participants": 2, "questions": 1}
    ]
  },
  "artifacts": [
    {"path": ".treffen/collection/decision-core/jobs.ep", "type": "Jobs"},
    {"path": ".treffen/collection/migration-interview/jobs.ep", "type": "Jobs"},
    {"path": ".treffen/collection/manifest.json", "type": "manifest"}
  ],
  "next_steps": [{"kind": "organizer_approval", "action": "deploy"}]
}

The roster needs names and stable participant IDs. Email is optional. A name-only EDSL AgentList still gives every person a tracked private link.

Expected Parrot Humanize hosts the survey. Preview the generated EDSL survey once more at the hosting boundary.

$ ep humanize preview --survey \
  vendor-decision/.treffen/collection/decision-core/survey.ep

After the organizer approves what participants will see, create the hosted survey.

$ ep humanize create \
  --jobs vendor-decision/.treffen/collection/decision-core/jobs.ep \
  --name "Analytics vendor meeting prep"

Register the returned survey UUID so Treffen can track collection state.

$ treffen -C vendor-decision collection register decision-core \
  --human-survey <survey-uuid>

The adaptive interview follows the same hosting boundary. Create and register it separately so its two assignments and responses remain traceable.

$ ep humanize create \
  --jobs vendor-decision/.treffen/collection/migration-interview/jobs.ep \
  --name "Analytics migration follow-up"

$ treffen -C vendor-decision collection register migration-interview \
  --human-survey <interview-uuid>

Email is not required. Export person-specific links and optional QR codes, then send each participant only their own link.

$ ep humanize links <survey-uuid> \
  --output vendor-decision/survey-links.csv \
  --qr-dir vendor-decision/respondent-qr

{"status":"ok","data":{"human_survey_uuid":"survey-uuid",
 "saved_to":"vendor-decision/survey-links.csv","respondent_count":4,
 "qr_directory":"vendor-decision/respondent-qr","qr_count":4,
 "sensitive":true},"warnings":[]}

Export the two interview links the same way for Alice and Chen.

$ ep humanize links <interview-uuid> \
  --output vendor-decision/interview-links.csv

Distribute without email

The organizer opens the link table and sends each person only their assigned URL through Slack, Teams, or direct message. The name-to-link mapping stays organizer-private.

Or let Humanize send and remind

treffen -C vendor-decision collection deliver decision-core \
  --name "Initial meeting prep" \
  --subject "Five-minute prep for Thursday's vendor decision" \
  --template invitation.html

A reminder can target only people who have not started rather than resending to everyone.

treffen -C vendor-decision collection remind decision-core \
  --not-started --schedule-at "2026-08-12T09:00:00-04:00"

Check response coverage without exposing anyone's answers.

treffen -C vendor-decision collection status --human

Priya Shah     completed
Alice Wu       completed
Chen Okafor    completed
Marco Ruiz     not started · reminder scheduled

Coverage: 3 of 4 participants

6. Retrieve the responses

Humanize returns standard EDSL Results. Treffen copies the source package into its evidence store, records a content hash, and normalizes surveys and interview transcripts into one response schema.

Download completed responses as a durable EDSL Results package.

$ ep humanize responses <survey-uuid> \
  --output vendor-decision/survey-responses.ep

Then give that package to Treffen. The original stays intact while Treffen creates normalized evidence records for analysis.

$ treffen -C vendor-decision collection ingest decision-core \
  --results vendor-decision/survey-responses.ep

Retrieve and ingest the interview result as a separate evidence package.

$ ep humanize responses <interview-uuid> \
  --output vendor-decision/interview-responses.ep

$ treffen -C vendor-decision collection ingest migration-interview \
  --results vendor-decision/interview-responses.ep

Survey responses: 3
Completed interviews: 2
Eligible participants: 4
Coverage warning: Marco's budget perspective is still missing
Source packages: sha256:4d8… · sha256:92a…

What came back

Before asking a model to summarize anything, the organizer can inspect the normalized evidence. This small excerpt shows why the question types matter.

7. Turn responses into reviewable findings

Deterministic work—counts, coverage, ranges, and missing participants—runs locally. Semantic clustering and crux classification use an inspectable EDSL synthesis job. Model output is only a proposal: every citation and count must validate before organizer review.

treffen -C vendor-decision synthesis build

Run required: ep run .treffen/synthesis/syn_01/jobs.ep \
  --output synthesis-results.ep
Then: treffen synthesis ingest syn_01 --results synthesis-results.ep

Run the inspectable EDSL job after approval.

ep run vendor-decision/.treffen/synthesis/syn_01/jobs.ep \
  --output vendor-decision/synthesis-results.ep

Ingest the result so Treffen can validate its evidence references and recompute quantitative claims.

treffen -C vendor-decision synthesis ingest syn_01 \
  --results vendor-decision/synthesis-results.ep

Now list the proposed findings in a readable form.

treffen -C vendor-decision synthesis list --human

F01  crux_factual  Alice estimates 2 weeks; Chen estimates 6.      medium
                       Structured estimates differ by 4 weeks.
F02  consensus     Internal build ranks last for all respondents.  high
F03  crux_values   Criterion budgets split on speed vs control.    medium
                       Speed: median 35/100 · Control: median 30/100
F04  theme          Confidence ranges from 4 to 9 on a 0–10 scale. medium
F05  gap           Finance constraint missing: Marco has not responded. high

The organizer opens each finding, follows its response references, and approves, edits, or rejects it. Editing changes the claim but preserves the generated predecessor and citations.

treffen -C vendor-decision synthesis show F01 --human

If the evidence supports it, approve it. Repeat the inspect-and-review step for each finding; edit or reject claims that overstate the responses.

treffen -C vendor-decision synthesis review F01 --approve

8. Create the pre-read and meeting plan

Only reviewed findings feed meeting design. The factual estimate becomes an async fix-it; rejected options and shared context go into the pre-read; the values crux receives most of the agenda.

treffen -C vendor-decision design build

Open the pre-read first. It carries shared context and settled points so participants do not need to reconstruct them aloud.

treffen -C vendor-decision design show pre-read --human

ANALYTICS VENDOR DISCUSSION — PRE-READ

Purpose
Choose among Buildly, MetricFlow, and an internal build.

What appears settled
• Internal build ranked last among the three respondents.
• The remaining choice is Buildly or MetricFlow.

What remains unresolved
• Implementation speed versus long-term data control.
• Migration effort: Alice estimates 2 weeks; Chen estimates 6 weeks.
  Their estimates use different identity-mapping assumptions.

Missing perspective
• Marco has not responded, so the year-one finance constraint is not yet
  represented in the findings.

Before Thursday
• Alice and Chen: reconcile the identity-mapping assumption asynchronously.
• Organizer: obtain or explicitly waive Finance's input.

Then inspect the proposed agenda. It allocates time to what remains unresolved.

treffen -C vendor-decision design show agenda --human

Recommendation: HOLD, but resolve migration estimate first

00:00–02:00  Confirm outcome and known constraints
02:00–05:00  Confirm internal build is out
05:00–20:00  Discuss speed versus data control
20:00–27:00  Choose Buildly or MetricFlow
27:00–30:00  Record owner, dissent, and next action

Use the materials with a meeting agent

The agent does not need the private response store. Give it the approved pre-read and agenda, then state the narrow facilitation job:

Use pre-read.md and agenda.md to help facilitate this meeting.

Keep the discussion on the unresolved speed-versus-control tradeoff. At the
start, check whether Alice and Chen reconciled the identity-mapping assumption.
Do not reopen the internal-build option unless someone presents new evidence.
Warn me at 20 minutes, and reserve the final three minutes to record the choice,
owner, dissent, and next action.

This handoff is deliberately based on reviewed participant-safe materials, not raw answers or private bearer links.

Before sharing anything, check the participant-facing view for private evidence or bearer links.

treffen -C vendor-decision privacy check --audience participants

After organizer approval, export the pre-read and agenda. The organizer can also give these evidence-backed materials to a meeting agent as its briefing.

treffen -C vendor-decision export \
  --audience participants --format html --output vendor-decision/exports

9. Record what happened

After the meeting, the organizer supplies notes or a transcript. Treffen reconciles the outcome against the pre-work and drafts a durable record rather than pretending the pre-meeting synthesis was the final truth.

First record actual attendance. This is separate from the expectations entered before the meeting.

treffen -C vendor-decision closeout attendance set priya attended

Repeat for the other participants, then attach the organizer's notes.

treffen -C vendor-decision closeout add-notes meeting-notes.md

Build and inspect the closeout record.

treffen -C vendor-decision closeout build

treffen -C vendor-decision closeout show --human

Decision: Choose MetricFlow
Why: Faster implementation outweighed the control advantage of Buildly
Dissent: Alice preferred Buildly's ownership model
Owner: Chen
Open action: Validate six-week migration plan by August 20
Reconciliation: F03 resolved; F01 estimate converged at five to six weeks

Attendance outcome: Priya attended · Alice attended · Chen absent · Marco attended
Expectation misses: Chen was expected but absent; Marco was not expected but attended

treffen -C vendor-decision closeout approve --revision <closeout-hash>

What the CLI contributed