v1.38.0 ·
A failure that says what to do
The problem
Every phase skill, the review skill, and the two CLI gate commands end by reporting a state
and stopping. Reported from observability-streams on 2026-09-29: after a review the agent
listed 26 findings by severity and said "aidlc gate still fails, but only because the design
phase is marked in-progress". It did not say that three findings needed the user's decision,
that seven were mechanical fixes it could apply, or that aidlc transition is the command
that marks the phase complete.
The gate half is structural. aidlc gate fails on "phase is still in progress" by design,
because aidlc transition is the step that sets complete. Nothing tells the reader so.
The one place that already does this is aidlc review (commands/review.ts:252, a
"Next steps:" block). It never spread.
How it could be solved
Three decisions, each about who the advice is for.
The first was where the advice should go. Adding a fix to the end of every failure line was the obvious move, and it reads badly: ten unfinished tasks would print the same instruction ten times. So the failure lines stay exactly as they were, and one list at the end gives one step per kind of failure. Anything that already reads those lines keeps working.
The second was what to do in a build pipeline. The one piece of advice that matters most — run the
transition command, which is what completes a phase — is wrong there: a pipeline checks the
committed work and cannot move it forward. So the gate looks for the CI variable, which the common
pipeline services all set, and in that case says the phase is still open and suggests nothing to
run. A pipeline that does not set the variable gets the ordinary advice, which is unhelpful rather
than harmful.
The third was how to change what the agent says without copying the same paragraph into eight guides. The rule lives in one file, and each guide gets one sentence pointing at it. It also says nothing about who marks a phase complete: that question is open in another backlog item, and this change was not going to add a new answer to it.
How AIDLC solves it
When aidlc gate or aidlc transition fails, its output now ends with a numbered list of what to
do: write these two files, close these three tasks, review this artifact, then run this command.
Each kind of failure gets one step, however many times it occurred, and the steps use the real
instance, phase and file names.
The most confusing failure now explains itself. aidlc gate fails on any phase not yet marked
complete, and aidlc transition is the command that marks it — so a gate run before the
transition always fails. The output now says exactly that, and names the command.
In a CI pipeline the advice changes. Nobody in CI can run a command that moves the lifecycle
forward, so when the CI variable is set the gate says the phase is still open in the committed
state and suggests nothing to run. Output requested as JSON is unchanged, byte for byte.
The agent side gets the same habit. A new shared rule tells it how to end a phase or a review: put every open item in one of two groups — decisions only the user can make, asked as questions, and fixes with one right answer, offered together in one step — then close with a single next command. Every phase guide points at the rule, and the review guide follows it. A review that used to end on "26 findings" now ends on three questions, seven fixes and one command.