fix(agents): break the hedging-at-the-root pattern — deferred(unclear), impacts field, reviewer detection

Address the root cause of rework-causing hedging: the architect was
put in a logical bind where it couldn't express justified uncertainty
('the pieces exist but the shape isn't clear yet'). The only options
were 'decide now' (premature) or 'deferred(scope)' (false — the
information isn't missing, it's un-synthesized). The agent picked
deferred(scope) with a circular blocking condition (OQ-64 blocked on
OQ-55, OQ-55 needs OQ-64) because there was no honest way to say 'I
can see the pieces but I can't see the shape.'

Changes to the architect role spec:
- Add deferred(unclear) state: the pieces exist but the composition
  isn't clear; resolution requires investigation (work through
  examples, POC), not waiting. Has an investigation target and an
  impacts field.
- Add 'Impacts' field to the OQ format: what does this block
  downstream? Be specific ('blocks the first hub deployment because
  the hub dials workers' not 'blocks the hub crate'). The triage
  signal that makes deferral urgency visible — the field that would
  have made the AlknetClient circular hedge visible.
- Add circular-reasoning guard to self-review: 'check that your
  blocking condition isn't a prerequisite of the thing you're
  deferring.'
- Trim anti-patterns #9-#11 (hedging synonyms catalog, ~40 lines):
  detection belongs in the reviewer, not the architect's self-review.
  The architect is too close to its own reasoning to see its own
  circular hedges.
- Trim door-types section (30→10 lines): keep the one-paragraph
  summary, cut the elaboration.

Changes to the architecture-reviewer role spec:
- Add Decision Quality (F) category: false-deferral check
  distinguishing three cases — (1) hedging on a resolved decision, (2)
  false deferral / circular hedge (the blocking condition is a
  prerequisite of the thing being deferred), (3) legitimate deferral.
- Add Impacts Field Coverage (G) category: check that unresolved OQs
  have specific impacts fields.
- Note: the Decision Quality category is often the highest-value
  check on poorly-defined projects — the architect cannot self-review
  it (circular reasoning is invisible from inside the circle).

Retrofit existing OQs:
- Add Impacts field to all 16 unresolved OQs (10 deferred, 6 open).
- Update OQ-63 (TlsError shape) to reflect ADR-087's client-side
  addition — the error type now covers both server and client
  variants.
- Move OQ-65 (WebSocket carrying channels) to alknet-http theme
  (done in prior commit; this commit adds its impacts field).
- Verified: no circular reasoning found in existing deferrals. The
  AlknetClient hedge (OQ-64) was the circular one; it's already
  resolved by ADR-087.
This commit is contained in:
glm-5.2 committed 2026-07-15 07:35:55 +00:00
1 parent bd9ae3cb68
commit 5941280bca
19 files changed
+300 -111

No files matched your search

+93
View File
@@ -82,6 +82,91 @@ Check coverage of:
- **Maintainability**: Testability, observability, modifiability
- **Scalability**: Horizontal/vertical scaling approach
#### F. Decision Quality and Deferral Honesty
This is the category the architect cannot do for itself — the architect
is too close to its own reasoning to see its own circular hedges. A
fresh context can see the whole picture and spot reasoning that folds
back on itself. This is often the highest-value category on projects
creating new protocols or solving poorly-defined problems, where the
shape isn't always clear and the architect may reach for a deferral to
avoid committing to an unclear shape.
Check for three cases:
**1. Hedging on a resolved decision.** An OQ marked `resolved` whose
resolution contains temporal language or escape hatches:
- "v1 default," "phase_n," "when x arrives," "can be revisited" — if
the decision is made, state it cleanly. Reserve temporal language
for genuinely deferred decisions.
- "feature extension, not an unmade decision" — if it's not decided,
it's not resolved.
- "additive, not blocking" — if it's not decided, don't claim it is.
- "two-way door — can be changed later if needed" — door type
classifies reversal cost, not whether a decision is made.
- "not a v1 blocker" — if it's not decided, it's deferred. Say what
unblocks it.
- "for now" / "not yet" on a resolved OQ — if the resolution has an
expiration date, it's not resolved.
- Resolution text primarily about how the decision can be changed
later ("X, but here's how we'd undo X") — the decision is made; drop
the undo instructions. If it's "X for now, Y later," the decision is
not made.
Flag as **critical**: the decision is either made (state it cleanly,
drop the hedge) or not made (mark it `deferred(scope)` or
`deferred(unclear)`). It cannot be both.
**2. False deferral / circular hedge.** A deferred OQ whose blocking
condition is a *prerequisite* of the thing being deferred, not a
blocker. This is the most damaging pattern — it creates a circular
dependency where the deferred thing can never resolve because its
blocker needs it.
Check each deferred OQ:
- For `deferred(scope)`: does the blocking condition *need* what this
OQ is deferring? If A is "blocked on B" and B needs A, that's a
prerequisite inversion, not a deferral.
- For `deferred(unclear)`: is the investigation target actually the
thing being deferred? If the investigation is "wait for X to exist"
and X needs this decision, it's circular.
- Is the information actually missing (`deferred(scope)` is correct),
or do the pieces exist but the shape wasn't synthesized
(`deferred(unclear)` is correct), or do the pieces *and* the shape
exist and the architect just didn't see the composition (should be
`resolved` — the decision is ready to make)?
Flag as **critical**: the deferral is circular or inverted. Suggest
the correct state — `resolved` if the pieces compose, `deferred(unclear)`
if the pieces exist but the shape needs investigation, `deferred(scope)`
only if the information genuinely is missing.
**3. Legitimate deferral.** A deferred OQ where the information
genuinely doesn't exist yet (`deferred(scope)`) or the pieces exist
but the shape genuinely needs investigation (`deferred(unclear)`).
Leave these — they're honest. The distinction from case 2 is that
the blocking condition or investigation target does *not* depend on
the thing being deferred.
#### G. Impacts Field Coverage
Every unresolved OQ (`open`, `deferred(scope)`, `deferred(unclear)`,
`partially resolved`) should have an **impacts** field stating what it
blocks downstream. Check:
- Is the impacts field present? Absence is a warning — without it, the
deferral's urgency is invisible and triage is guesswork.
- Is it specific? "Blocks the first hub deployment because the hub
dials workers" is useful. "Blocks the hub crate" is boilerplate.
- Does it match the priority? A `deferred(unclear)` with high priority
but a vague impacts field ("blocks future features") is a mismatch —
if it's high priority, it blocks something specific; say what.
Flag missing impacts fields as **warning**, vague ones as
**suggestion**.
### 3. Categorize Findings
**Critical**: Must fix before stabilization
@@ -90,6 +175,8 @@ Check coverage of:
- Missing quality attributes with significant impact
- Architectural decisions without rationale
- Inconsistencies in the specification
- Hedging on a resolved decision (case 1 of Decision Quality)
- Circular or inverted deferrals (case 2 of Decision Quality)
**Warning**: Should fix if possible
@@ -97,12 +184,14 @@ Check coverage of:
- Missing edge cases
- Incomplete interface definitions
- Implicit assumptions
- Missing impacts fields on unresolved OQs
**Suggestion**: Consider but optional
- Alternative phrasing
- Additional context that might help
- Documentation organization improvements
- Vague impacts fields on unresolved OQs
### 4. Write Review Report
@@ -168,3 +257,7 @@ section 2"
- Focus on architecture-level issues, not code-level
- Be constructive and specific
- Critical issues must block stabilization
- The Decision Quality (F) category is often the highest-value check on
projects creating new protocols or solving poorly-defined problems.
The architect cannot self-review this category — circular reasoning
is invisible from inside the circle. Prioritize it.