Status: proposed Date: 2026-05-19
Agents with fresh context (tabula rasa) attempt to follow documentation and hit gaps they cannot resolve. These gaps are silently worked around (agent asks a human) rather than systematically fixed. The system cannot self-improve its onboarding because failures are not captured.
Knowledge acquisition starts from zero. Each iteration creates the roadmap to better knowledge by discovering gaps through actual failures.
Periodically, an agent with no project memory attempts to follow guides end-to-end. The agent follows ONLY what is written — no inference, no training data knowledge, no asking colleagues.
At each failure point, the agent:
- Stops — does not attempt to work around or guess
- Documents — creates an issue: which document, which step, what was missing
- Continues — attempts the next step (if possible) to find additional gaps
After completing a task, project milestone, or sprint, agents produce a retrospective artifact:
- What worked well (patterns to repeat)
- What failed or caused friction (patterns to avoid)
- Actionable experiments for future workflows
Retrospectives are a first-class knowledge artifact — they feed into documentation improvements, inform ADR amendments, and surface systemic issues that individual task failures cannot.
Until documentation meets ADR-004, agents may create ephemeral artifacts:
- Semantic indices of the codebase (call graphs, dependency maps)
- Annotated walkthroughs of successful executions
- "What I learned" summaries after completing a task
- Retrospectives (see above)
These are scaffolding that informs documentation improvements, not documentation themselves.
| Level | State | Agent capability |
|---|---|---|
| 0 | No docs | Cannot start; files issue for missing docs |
| 1 | Partial docs | Follows docs, stops at gaps, files issues |
| 2 | Complete docs (ADR-004) | Completes end-to-end without help |
| 3 | Self-improving | Detects drift between docs and code, auto-files issues |
Agent starts fresh → follows docs → hits failure →
files issue → issue gets fixed → next agent goes further →
hits next failure → files issue → ...
until end-to-end works from zero context
This runs continuously because code changes outpace documentation and different agent implementations fail at different points.
- (+) Documentation gaps become bugs with reproduction steps
- (+) Priority ordering emerges naturally (most common failures surface first)
- (+) The system self-improves without human identification of gaps
- (+) Creates a natural definition of "docs are done" (Level 2 achieved)
- (-) Generates issue volume that needs triage
- (-) Requires periodic investment in zero-context test runs
- (!) The gap between Level 1 and Level 2 may be large — patience required
- Issue #138 — full RFC with open questions
- ADR-004 — defines the quality target (tabula rasa test)
- ADR-003 — governance for issues filed by failing agents
- ADR-008 — Level 4 Definition of Done depends on this protocol