Authoring Interview Workflows

This page is for workflow authors - org admins or developers who build and maintain workflows on the canvas. If you are a participant looking for the end-user experience, see Running an Interview.

The Interview palette group

Interview nodes appear in their own Interview group in the node palette (between Composition and Orchestration). Open the palette, scroll to Interview, or type interview in the palette search.

The group contains seven nodes:

Node reference

Interview Config

Node id: interview.config

The Interview Config node is the central declaration for a conversation. It carries the model profile, persona card, capacity pool, and the ordered list of interview phases. Other nodes (Interview Phase, Interview Launch) reference it by wiring into its input ports.

Input ports

Each input port has a Wire / Inline toggle in the config panel. In Inline mode you edit the value directly in the panel. In Wire mode the inline controls lock and the port expects an upstream edge - the compiled definition reads the wired value.

Output ports (result paths)

Phase composition: Wire-or-Inline

The phases slot supports two authoring styles:

• Inline phases (default). Open the config panel, go to the Phases section, and click + Add Phase. You can choose from the six canonical phases (Context, Users, Core Problem, Features, Constraints, Success Criteria) or add a custom phase. Each phase has a title, orienting headline, rubric, and optional chip hints. Phases are reorderable with the up/down arrows on each row.
• Wired phases. Drop one or more Interview Phase nodes on the canvas, connect their output ports to the phases input port of the Interview Config node, and set the phases slot toggle to Wire. The compiled definition reads phases in wire order. Use wired phases when you want to share a phase definition across multiple configs or when a phase is generated upstream.

Config panel sections

Interview Phase

Node id: interview.phase

Defines a single phase of the interview. Use when you want to wire distinct phases into an Interview Config rather than edit them inline.

Ports

Config fields

Create Interview Issue

Node id: interview.create_issue

Creates a tracker issue from the completed User-Spec. Appears in both the Interview and Issue Tracking palette groups.

Ports

Key config fields

The node is idempotent on interviewId: if the interview has already produced a tracker issue, the node returns the stored issue id without writing again.

Interview Started (trigger)

Node id: trigger/interview.started

A canvas placeholder that makes the interview-started event visible in the workflow definition. It appears in the Triggers palette group (not Interview).

This node does not register a live webhook subscription. Interviews are launched imperatively - either by a participant opening the interview URL or by an Interview Launch node inside a running workflow. The trigger node exists so the interview-v1 template canvas is readable and the trigger envelope shape is visible to authors inspecting the YAML.

Trigger envelope output

Interview Launch

Node id: interview.launch

An action node that mints a new interview instance, notifies the recipient, and passes the interview id to downstream nodes - specifically to a paired Interview Gate. Use this node in the conditional archetype (A5) when an agent's fail path should route through a user interview before continuing.

Ports

Config panel fields

Hard precondition

Interview Launch hard-fails at runtime if the project does not have a published interview-v1 template. Without it, no inner interview instance runs, the gate never receives a completion signal, and the workflow would stall indefinitely. Install and publish interview-v1 on the project before activating any workflow that uses Interview Launch. See Interview Template.

Interview Gate

Node id: interview.gate

A gate node that suspends the workflow until the interview launched by an upstream Interview Launch node finishes. On resume it routes to a named output handle based on the outcome.

Interview Launch and Interview Gate are always used as a pre-wired pair. The interview-conditional-v1 template drops them together. You can also wire them manually: connect the output port of Interview Launch to the input port of Interview Gate, then wire the complete, abandoned, and timeout handles to downstream nodes.

Ports

Referencing gate output downstream

Downstream nodes (typically Create Interview Issue, agent dispatch) read the gate's result using {{ nodes.<gateNodeId>.output.<field> }} expressions:

{{ nodes.interview_gate.output.spec }}
{{ nodes.interview_gate.output.userIntent }}
{{ nodes.interview_gate.output.interviewId }}

Auto-bind does not derive these expressions automatically - you must author them explicitly in the downstream node's config panel or YAML.

Emit Gate Completed

Node id: interview.emit_gate_completed

A thin action node that emits the inner-to-outer completion signal. It appears at the end of the inner interview-v1 template canvas, wired after Create Interview Issue.

As a workflow author you will not need to drop this node manually - it is pre-wired in the interview-v1 template. It is visible on the canvas so that the cross-instance signal (the bridge that resumes the outer workflow's Interview Gate) is explicit rather than hidden inside the issue-creation step.

The node is a no-op when no outer gate is waiting, so installing interview-v1 on a project that has no A5 workflows is safe.

Archetypes

Archetype A4 - Start with a conversation

Use this pattern when the primary entry point for a project's work is a user interview: the participant starts the interview, works through all phases, and the platform creates a tracker issue and dispatches the research → backlog pipeline automatically.

This is the default interview-v1 template. Install it on the project and it handles the full flow without canvas editing.

Canvas shape (simplified):

[trigger: interview.started]
        ↓
[interview.config]   ←  optional: wire model/persona/pool/phases
        ↓
  (built-in gate: waits for interview completion)
        ↓
[interview.create_issue]
  issueDescription = {{ nodes.interview_v1_wait_gate.output.issueDescription }}
  interviewId      = {{ trigger.data.interviewId }}
        ↓
[agent dispatch: research]
        ↓
[agent dispatch: backlog-writer]

Flow:

1. A participant opens the project's interview URL or is directed there by the platform.
2. The agent guides them through the configured phases.
3. The participant clicks Send to Rensei at the end of the six-phase conversation.
4. Create Interview Issue writes the User-Spec to the tracker.
5. The research → backlog-writer chain runs automatically.
6. The finished backlog item advances to Triage, where the standard SDLC takes over.

When to use it: the spec does not yet exist and needs to be elicited from a non-technical stakeholder. Works well for new features, scoping sessions, and discovery work.

Archetype A5 - Conditional interview (fail-path elicitation)

Use this pattern when a running agent lacks sufficient context and needs to pause and gather requirements from a user before continuing. An agent processes an issue, determines it cannot proceed (missing context, ambiguous requirements, no spec), and routes its fail path into an interview. When the user finishes the interview the outer workflow resumes with the gathered spec.

This is the interview-conditional-v1 template.

Canvas shape:

[trigger: agent.exit]
      ├─ success ──→ [continue / close]
      └─ fail    ──→ [interview.launch]
                           ↓ (plain edge)
                     [interview.gate]
                        complete │  timeout │  abandoned │
                            ↓          ↓          ↓
                    [interview.create_issue]  [escalate]  [terminal]
                      spec       = {{ nodes.interview_gate.output.spec }}
                      interviewId = {{ nodes.interview_gate.output.interviewId }}
                            ↓
                    [agent dispatch: research]
                            ↓
                    [agent dispatch: backlog-writer]

Flow:

1. An agent processes an issue and returns a fail result (missing context or explicit handoff signal).
2. Interview Launch mints a new interview instance and sends a notification to the designated recipient.
3. The outer workflow suspends at Interview Gate.
4. The recipient opens the interview URL, completes all phases, and submits.
5. The inner interview-v1 instance writes the tracker issue, then emits the completion signal.
6. Interview Gate resumes and routes to complete.
7. Create Interview Issue receives spec and interviewId from the gate's output.
8. The research → backlog-writer chain runs with the fresh spec.

Setup requirements:

• interview-v1 must be installed and published on the project (Interview Launch hard-fails otherwise).
• The Interview Launch node's Recipient field must identify the org member who will be interviewed. This person receives an in-app notification when the interview is ready.
• Wire the timeout handle to a meaningful fallback - at minimum an escalation or a closing action.

Result path bindings (copy these into the downstream node's config):

Replace <gateId> with the node id shown in the canvas - hover the Interview Gate node and copy the id from the config panel header.

Result paths and downstream routing

Both archetypes produce a User-Spec that downstream nodes consume. The result shape is the same regardless of archetype:

Routing the timeout path

When a gate times out without a completion signal:

• The timeout output carries an empty spec and userIntent.
• Do not wire a Create Interview Issue node on the timeout path - an empty spec produces a low-quality tracker issue.
• Recommended: wire to an escalation node (email, Linear comment, or Slack notification) that tells the requestor the interview timed out and needs to be restarted.

Routing the complete path

The complete output carries the full spec. The canonical downstream sequence is:

[complete] → [interview.create_issue] → [agent.dispatch_stage: research]
                                              ↓
                                        [agent.dispatch_stage: backlog-writer]

Installing the built-in templates

interview-v1 (A4 archetype)

The interview-v1 template is the canonical start-with-conversation workflow. Install it on any project where interviews are the entry point for new work. An operator installs it from a platform checkout:

pnpm tsx scripts/install-authored-interview-v1.ts --org my-org --project my-project

Verify in the project's Workflows → System Templates panel - interview-v1 should show as Published. See Interview Template → Installing for the full install reference (there is no self-serve install UI or rensei CLI command for template installs today).

interview-conditional-v1 (A5 archetype)

The interview-conditional-v1 template is the conditional fail-path archetype. It ships with Interview Launch and Interview Gate pre-wired and result-path bindings pre-authored. The same installer handles it via --template:

pnpm tsx scripts/install-authored-interview-v1.ts --org my-org --project my-project --template interview-conditional-v1

interview-v1 must also be installed on the same project - the conditional template depends on it for the inner interview instance.

Common authoring mistakes

Related pages

• Overview - what interviews are and how they fit in the pipeline
• Running an Interview - the participant experience
• Interview Template - the interview-v1 template reference
• Configuration - enabling interviews and selecting a model profile
• Gate Node - how gate nodes suspend workflows (general reference)
• Workflow Canvas - the canvas editor reference
• Expressions - the {{ nodes.<id>.output.<field> }} binding syntax