ADR-0014: AI surfaces unknowns via REVIEW.md “Proposed work”
Status: Accepted Date: 2026-05-19
Context
User stated: “I might need help coming up with good questions, because most of the time I don’t know what I don’t know.” Question notes serve two roles: recording user’s own open inquiries AND giving AI a handle to surface gaps in user’s understanding.
Decision
Every batch’s REVIEW.md includes a Proposed work section with three lists:
1. Open questions raised — max 3, prioritized
Tagged [critical | interesting | minor]. Each question cites the specific note(s) and source(s) that triggered it (no vibes-based proposals).
priority: field placement: The priority tag MUST be written as a frontmatter field (not in the note body). When AI promotes a proposed question to a Question note in /questions/, it must include priority: [value] in the YAML frontmatter block alongside status:, tags:, etc. Body-only placement is a schema violation caught by the pre-commit hook.
Default: promote to Question notes. When the user approves a batch, ALL proposed questions become real Question notes in /questions/ unless the user explicitly rejects specific ones (“skip Q2”). User can also edit any question’s wording during review. This default was clarified after batches 1–3 produced 9 questions that were initially logged as “not promoted” — user explicitly wanted them all saved. See feedback-questions-default-promote in memory.
2. Proposed threads
When a tag cluster has 5+ atomics with no thread yet, AI proposes one with seed atomics listed. User accepts (“draft next batch”) or rejects (“premature”).
3. Stale wrestling
Threads with ## Response saying “Still wrestling” that haven’t been touched in 3+ batches. AI surfaces them for user attention. This is the safeguard against quietly abandoning doubts.
Rejected proposals are remembered
A _meta/rejected-proposals.md log. When user explicitly rejects a proposed Q/thread/stale-flag (e.g., “skip Q2”, “no thread yet”), AI logs it. Next batch AI does not re-propose unless materially new evidence emerged. Prevents nag loops.
Note: only explicit rejections land here. Silence or general approval means promote.
Every proposal must cite WHY
No proposal lands in REVIEW.md without specific note/source references that triggered it. If you can’t see the trail, AI overreached.
Alternatives considered
- No cap on proposed questions: rejected — more than 3 = wall of text, user skims and ignores.
- AI proactively writes the questions without asking: rejected — drowns user in noise; better to propose and let user judge importance.
- Stale-wrestling surfaced as a separate cron job: rejected — easier to surface during the batch flow user is already reviewing.
Consequences
- (+) AI actively pushes user toward synthesis (thread proposals) and honest re-engagement (stale wrestling) rather than passively filing
- (+) Capped proposals keep REVIEW.md readable
- (+) Rejected log prevents AI from nagging on settled matters
- (−) AI’s question quality is a judgment skill that will improve over time; user feedback in early batches will calibrate