Motivation
Braid's HITL loop has three soft spots in how it handles uncertainty, and they are really one theme.
- ClarifyTickets carry no typed reason. A ticket records a question plus candidate resolutions, but not why the graph was uncertain: a genuine ambiguity, an unconfirmed assumption, a missing fact, or a contradiction. Without that, the reviewer inbox cannot prioritise, and
reconcile cannot treat a cross-graph contradiction differently from a local gap.
reconcile triages by a binary rule. Today it auto-applies format fixes and turns every semantic decision into a ClarifyTicket. That is coarse. Many cross-link fixes (a missing back-reference edge, a terminology mismatch) are mechanical and safe to propose without a human question, while only genuine design calls (which aggregate owns this command) warrant a ticket.- No explicit convergence guarantee. Answering one ticket can make other pending tickets moot, and a
reconcile re-run can re-surface an ambiguity the reviewer already skipped. Nothing enforces that the open-question count only goes down.
Framed positively: the clarify and reconcile skills should form a single confidence-triaged loop that provably converges. Braid is well positioned for this because the graph gives global cross-linking natively, so reconcile already is the global-consistency pass. The work is making that pass smarter, not bolting on a separate analyzer.
Proposal
Three coherent pieces, in dependency order.
1. Typed ambiguity category on ClarifyTicket (the keystone)
Add a closed category to every ClarifyTicket capturing why it was raised. A workable taxonomy, aligned with EventStorming hotspots and general spec-clarification practice:
ambiguity — the source admits more than one reasonable reading.assumption — the extractor made an unconfirmed choice worth surfacing.gap — required information is absent from every source.conflict — two sources, or a source and the current graph, contradict.boundary — a scope edge is unclear (in-context vs out-of-context).
Consumers: the Studio inbox and the clarify loop order conflict first (a contradiction cascades), then by blast radius; reconcile files its cross-graph contradictions as conflict tickets so they pre-empt local gaps. This piece is small (a schema field, emit sites in extract and reconcile, and display) but it is the axis the other two build on.
2. Confidence-graded triage in reconcile
Replace the binary format/semantic rule with a graded gate. For each candidate cross-link or fix, weigh how mechanical it is: is the fix unique, how wide is its blast radius, does it touch load-bearing structure. Mechanical, low-impact fixes (missing back-reference, casing, terminology alignment) auto-propose inside the reconcile Proposal; genuine design decisions escalate to a conflict or ambiguity ClarifyTicket. The threshold and dimensions want tuning against real runs, so this piece should be built and calibrated on live workspaces rather than fully specified up front.
3. Convergence discipline
Make the loop provably shrink the open-question set.
- After a resolution is applied, re-scan pending tickets and auto-close any the resolution made obsolete (its premise is now false) or superseded (implicitly answered).
- Never re-raise an ambiguity the reviewer previously skipped; a
reconcile re-run reads prior decisions and does not contradict them.
- Treat "open ClarifyTicket count decreases monotonically across a converging session" as an invariant worth asserting in tests.
Sequencing and scope
Build in order: category field, then conflict-first ordering, then reconcile triage, then convergence discipline. This is a deferred, cohesive theme; it should land as one designed piece rather than piecemeal, because each part is low-value without the others. An unused category is schema debt, and triage without the category loses the conflict-first axis.
Out of scope
The DDD node and edge vocabulary is not changed here. A separate open question is whether to add a readModel node for strict CQRS, currently folded onto the aggregate; that is independent of this loop.
Motivation
Braid's HITL loop has three soft spots in how it handles uncertainty, and they are really one theme.
reconcilecannot treat a cross-graph contradiction differently from a local gap.reconciletriages by a binary rule. Today it auto-applies format fixes and turns every semantic decision into a ClarifyTicket. That is coarse. Many cross-link fixes (a missing back-reference edge, a terminology mismatch) are mechanical and safe to propose without a human question, while only genuine design calls (which aggregate owns this command) warrant a ticket.reconcilere-run can re-surface an ambiguity the reviewer already skipped. Nothing enforces that the open-question count only goes down.Framed positively: the
clarifyandreconcileskills should form a single confidence-triaged loop that provably converges. Braid is well positioned for this because the graph gives global cross-linking natively, soreconcilealready is the global-consistency pass. The work is making that pass smarter, not bolting on a separate analyzer.Proposal
Three coherent pieces, in dependency order.
1. Typed ambiguity category on ClarifyTicket (the keystone)
Add a closed category to every ClarifyTicket capturing why it was raised. A workable taxonomy, aligned with EventStorming hotspots and general spec-clarification practice:
ambiguity— the source admits more than one reasonable reading.assumption— the extractor made an unconfirmed choice worth surfacing.gap— required information is absent from every source.conflict— two sources, or a source and the current graph, contradict.boundary— a scope edge is unclear (in-context vs out-of-context).Consumers: the Studio inbox and the clarify loop order
conflictfirst (a contradiction cascades), then by blast radius;reconcilefiles its cross-graph contradictions asconflicttickets so they pre-empt local gaps. This piece is small (a schema field, emit sites inextractandreconcile, and display) but it is the axis the other two build on.2. Confidence-graded triage in reconcile
Replace the binary format/semantic rule with a graded gate. For each candidate cross-link or fix, weigh how mechanical it is: is the fix unique, how wide is its blast radius, does it touch load-bearing structure. Mechanical, low-impact fixes (missing back-reference, casing, terminology alignment) auto-propose inside the reconcile Proposal; genuine design decisions escalate to a
conflictorambiguityClarifyTicket. The threshold and dimensions want tuning against real runs, so this piece should be built and calibrated on live workspaces rather than fully specified up front.3. Convergence discipline
Make the loop provably shrink the open-question set.
reconcilere-run reads prior decisions and does not contradict them.Sequencing and scope
Build in order: category field, then conflict-first ordering, then reconcile triage, then convergence discipline. This is a deferred, cohesive theme; it should land as one designed piece rather than piecemeal, because each part is low-value without the others. An unused category is schema debt, and triage without the category loses the conflict-first axis.
Out of scope
The DDD node and edge vocabulary is not changed here. A separate open question is whether to add a
readModelnode for strict CQRS, currently folded onto the aggregate; that is independent of this loop.