Clarify the workflow before adding more AI agents

A GitLab issue went to the wrong project

While building Intake, I considered dividing request intake among several AI agents. One agent would read the content, another would find missing information, a third would write the requirement and an orchestrator would decide what happened next.

Each capability looked reasonable on its own. One test showed that the real problem was the workflow, not the number of agents.

A project owner described a problem that needed attention. AI interpreted the content in the wrong context and created a GitLab issue for another project. The issue was structured and sounded plausible, but it did not represent the problem the sender intended to solve. The project owner had to describe it again so the context could be corrected.

An output can look complete and still be wrong at the source context. Passing that output through more agents only makes the wrong decision harder to detect.

The problem was not a shortage of agents

Intake receives information from several sources. The initial content can be missing project context, scope, ownership or the conditions that define completion.

Without those facts, an orchestrator has no reliable basis for deciding whether to ask another question, which project should receive the work or whether the request is allowed to become committed work. More agents do not create the missing context. They create more handoffs and more places to investigate when the result is wrong.

I returned to a simpler rule:

Before dividing a workflow among agents, each step needs an input, output, validity condition, action boundary and failure path that another person can inspect.

Define the output contract before orchestration

AI in Intake does not produce an open-ended description and then decide what to do next. Its output follows a defined structure:

• The problem to solve.
• The expected outcome.
• The scope of work.
• The responsible owner.
• The completion criteria.

Structured output is checked against a schema before it can continue. Missing required fields or an invalid structure do not become a valid request.

Schema can verify the shape of the data. It cannot prove that AI understood the correct project or the project owner’s intent. The system therefore retains the source content, draft versions, user edits and approval history so the responsible person can compare them.

Schema validation protects structure. Human review protects context and responsibility. These layers address different failures.

Public control flow

After stopping the multi-agent design at this stage, I reduced the workflow to one observable flow:

Input from several sources
    -> AI extracts a structured request draft
    -> Schema validation
    -> Responsible person compares it with the source
    -> Clarify or edit when information is missing
    -> Responsible person approves the action
    -> Create the GitLab issue

Two actions are controlled separately:

1. Send a clarification question to the requester.
2. Create a GitLab issue from the approved request.

AI can propose a question and prepare the issue content. It cannot send the question or create committed work without the corresponding approval.

This is a public responsibility model, not Intake’s internal architecture.

States need operational meaning

Instead of one generic “processed” state, the workflow distinguishes steps with different meanings:

received
  -> extracting
  -> needs_clarification
  -> review_ready
  -> awaiting_approval
  -> creating_gitlab_issue
  -> completed

failure paths
  -> validation_failed
  -> integration_failed

review_ready means only that the draft has enough structure for human inspection. It does not mean the content is correct. awaiting_approval means the action is still not authorized. completed appears only after the GitLab issue has been created successfully.

Separate states show operators whether work is waiting for AI, waiting for approval or failing at the destination integration. They also keep the interface from promising completion when the system has produced only a plausible description.

Controls already in place

The current flow uses different controls for different risks:

• Structured output and schema validation reject malformed output and missing required fields.
• Versioning distinguishes the AI proposal from the version edited by a person.
• An audit log records who changed, approved or triggered an action.
• Idempotency prevents a repeated request from creating duplicate GitLab issues.
• Human approval is required before sending a question or creating committed work.

None of these controls proves that the content is correct. They make the decision inspectable, traceable and recoverable when something fails.

Failure modes tested in practice

The team tested the following situations:

Situation	Risk	Expected response
AI returns an invalid structure	The next component reads the data incorrectly	Schema validation rejects the output
Required fields are missing	The request is not ready to become work	Move to clarification or wait for the responsible person to complete it
AI proposes an unsuitable question	A distracting question is sent to the requester	Reviewer edits or rejects it before sending
A user edits the AI proposal	An older draft may be used by mistake	Create a new version and approve only the current one
The same action is submitted more than once	Duplicate GitLab issues are created	Idempotency preserves one work-creation action
The GitLab integration fails	An approved request does not become work	Retain the failure state and evidence for retry or recovery

The wrong-project incident exposes another failure mode: an output can satisfy the schema and still be wrong in context. Technical validation alone cannot catch it. The reviewer needs the source content, destination project, AI draft and pending action in the same view.

When another agent has a reason to exist

Multiple agents are not inherently the wrong choice. But every new agent should represent an independent responsibility, not merely another prompt.

Before adding an agent, I ask:

1. Does this job have a sufficiently clear input and output of its own?
2. What schema, rule or evidence can verify the output?
3. Is the agent allowed only to propose, or also to act?
4. Where does the work go when the agent is uncertain or fails?
5. Is there a distinct failure mode large enough to justify separating the responsibility?
6. Does the separation improve observability and recovery compared with one focused flow?

If those questions do not have answers, another agent usually adds only another handoff.

What you can apply

When designing an AI-assisted workflow, start from a real action instead of the number of agents:

1. Identify the action that changes a system or affects another person.
2. Define the minimum information required before that action.
3. Separate structural validation from contextual validation.
4. Name the person who can approve the action and what evidence they need to see.
5. Use separate states for clarification, approval and destination integration failure.
6. Test duplicate submission, invalid output and an unavailable destination system.

Add another agent only when the workflow reveals another responsibility that should be separated. If the workflow is still unclear, clarify the input, decision rights and inspectable evidence first.

Disclosure boundary

This note describes the responsibility boundaries and the failure modes tested in practice. It does not disclose internal prompts, detailed schemas, credentials, deployment topology, customer data or private GitLab configuration.