Lesson 31 — Assumptions ledger

Outcome

Ask capable agents to record important choices they made without escalating and surface those Claims in Review.

Why this comes now

The dangerous failure is often the missing Decision: the agent made an assumption silently. The ledger narrows where a reviewer should look without pretending to replace review.

Understand

The Assumptions Ledger is agent-authored and therefore a Claim. It should be captured at a natural Turn boundary through the same structured integration channel used for narration/escalation when available. Missing ledger capability must degrade honestly, not fabricate assumptions.

Build the real project

1. Define a structured assumption entry: statement, reason/context, confidence/impact only if useful, related files/criteria optionally.
2. Extend capable adapter prompt/tool contract.
3. Store as Claims linked to Run/Turn/RawRef.
4. Surface in Review beside diff/criteria/verification.
5. Add fake scenarios with no assumptions, one assumption, and malformed output.
6. Measure whether ledger is helpful or verbose in several real Tasks.

Completion gate

Review clearly labels assumptions as agent-authored. Absence is shown as unavailable/none, not filled by Forge.

Pitfalls to avoid

Do not treat the ledger as proof that all assumptions were disclosed. Do not block Done merely because a provider lacks the capability unless product evidence later justifies it.

References

Archived Forge ADR-0008: docs/archive/01-previous-forge-overview.md; UX_PRINCIPLES.md.

Checkpoint

Record whether the ledger changed your review behavior. This feature exists to improve human judgement, not to produce more text.