Repository navigation
Delete ai-development.md §4 and put the prose doctrine in the root AGENTS.md #374
Description
Question
docs/process/ai-development.md §4 taught that a good acceptance criterion is a runnable command
carrying its pasted output and a citation that must still resolve. That bar is unreachable for prose,
so the work moved into lib/, and every merge invalidated every pending citation. Delete §4.
Then write the lesson where a session actually loads it — a short doctrine in the root AGENTS.md,
not a new process document. §4 was 222 lines of file; the replacement is a handful.
Three lessons from §4 are earned and must survive the deletion, compressed:
- Read the criteria as one set, not one at a time. Individually reasonable criteria can be
collectively impossible, and the dangerous shape is a gap between two of them that an
implementer fills with a defensible-sounding decision. - Turn the diagnosis on the cure. When a ticket says a thing rots because it is written by hand, read
the fix back and ask what is still written by hand. - A grilling ends by listing what it did not decide. "Either is acceptable" and "whichever fits" are
where an unanswered question hides.
Acceptance criteria
- §4 is gone from
docs/process/ai-development.md, and no other section restates its bar. - The root
AGENTS.mdstates that this repo's product is prose, that a criterion names an
observable outcome rather than a command with pasted output, and that nofile:linecitation is
binding inside a criterion. - It states that adding a module plus a test so that prose becomes testable is a defect, and names
lib/slopcheck.mjsas the worked example. - The three surviving lessons above appear, compressed, with no new process document created.
- Every remaining reference to §4 elsewhere in the repo is updated or removed.
Activity
orioltf commentedon Aug 14, 2026
How to start this session
Produces: §4 gone, a short doctrine in the root
AGENTS.md, one PR todevelop./wayfinder 373 #374. It claims this ticket.docs/process/ai-development.md§4 in full before deleting it. Three lessons must survivethe deletion — they are named in the ticket body.
/writing-for-agents. Read its context pointers section first: the doctrine is a contextpointer, and its wording decides whether a session reaches it. That is the lever here.
AGENTS.md. Keep it under about fifteen lines.seven places that say
ready-for-agentalone is enough to dispatch — fold them in here.feature/repo/<slug>, PR todevelop.Traps
defect one level up.
AGENTS.md. That is the antipattern this ticket exists to end.pnpm format, thenpnpm ci:checkbefore pushing, or the root checks fail.
orioltf commentedon Aug 14, 2026
Resolution
§4 is deleted. The doctrine lives in the root
AGENTS.mdas "Acceptance criteria are prose", ninelines, under Feature-driven development. PR #386 →
develop.What the doctrine states. The product is prose, so a criterion names an observable outcome —
what a document must state, checked by reading it. Not a command carrying its pasted output. No
file:linecitation inside a criterion binds, because the next merge moves the line. Adding a moduleplus a test so that prose becomes testable is a defect, with
lib/slopcheck.mjsas the workedexample: it exists only to be tested, while
.archon/workflows/unic-dlc-build.yaml:120inlines itsown copy and imports nothing.
The three lessons survive as the three reads a pre-dispatch audit runs: read the criteria as one
set (the dangerous shape is the gap between two of them); turn the diagnosis on the cure; close a
grilling by listing what it did not decide.
What died with §4. The runnable-command bar, the pasted-output rule, "every citation resolves",
the
rg -cworked example, "the ready queue is the hazard" (it scaled with citation count), and thefour-check list. The audit itself survives on three reads instead of four checks.
One design call worth naming.
night-shiftstopped the run when §4's checklist could not beread — a fail-closed guard against a missing external file. The doctrine sits in the always-loaded
root
AGENTS.md, so that file cannot be unreachable, and the clause is gone. If the doctrine is evermoved out of
AGENTS.md, that guard has to come back.Citations repointed.
docs/agents/triage-labels.mdstates the audit-comment rule itself and nolonger cites §4 for it;
night-shiftpoints attriage-labels.mdfor where the audited commit lives.Zero references to
ai-development.md§4 remain in the repo.#365 folded in. All seven
ready-for-agent-is-enough sites are amended —development-workflow.md:85/:93/:99and quick-reference row 7,CONTRIBUTING.md,triage-labels.md:22,ONBOARDING.md:51/:77. Most of #365's other criteria are moot because their sites were inside §4. Two remainopen and are out of this PR: the unreadable-label consequence stated once in
triage-labels.md, andwhether the shape-sweep lesson needs a home now that §4 does not exist. Both sweeps ran clean — see
the PR body.
pnpm ci:check,pnpm testandpnpm typecheckall exit 0. CI on #386 is green.Closing this ticket once #386 merges to
develop.docs(repo): restore the vacuous-criteria read, and home the shape-swe…
docs(repo): drop the pre-dispatch audit, return to Matt's workflow
docs(repo): cut the ready-queue habit to two homes
docs(repo): act on the Copilot findings that survived the reversal
docs(repo): stop the state-roles table contradicting the paragraph be…
orioltf commentedon Aug 14, 2026
Merged as
5366a4a(PR #386). Closed by the merge.The ticket shipped more than it asked for, because two decisions landed while it was open:
AGENTS.md— the ticket's own subject. Four reads, not three:the three lessons named here, plus §4's vacuous-criteria check, which was kept because it never
depended on the tree still matching the ticket.
dispatch, and that rot came from the citation requirement this ticket deleted. With the cause gone,
the gate had nothing left to do.
ready-for-agentmeans one thing again.soon. Stated in exactly two places:
AGENTS.md, always loaded, andai-development.md§2, with thereasoning and the trade. It is a trade: sometimes a stale ticket ships a wrong pull request, at a
cost of one run against the 2.5 hours the audit charged before every night shift.
Also in the PR, outside this ticket's subject and authorised separately:
docs/agents/triage-labels.md'sstate-roles cell no longer contradicts the paragraph two lines below it. #303 remains the mechanical
fix that a wording change does not replace.
Consequences recorded on their own issues: #365 (one criterion moot, one deliberately reversed),
#372 (the marker was removed, not fixed), #362 (two of three divergences gone, the third survives on
Gate 3). All three stay open for #375.