RFC: ADR-007 — Knowledge acquisition through progressive failure (self-improving documentation)

[scottschreckengaust]

Summary

Define the protocol for how agents acquire knowledge when documentation is insufficient: start from zero, follow docs diligently, stop at the failure point, create an issue for the gap, and iterate. Each failure improves the system for the next agent. Knowledge acquisition creates its own roadmap.

Use case and motivation

Problem today:

1. Agents with fresh context (tabula rasa) attempt to follow documentation and hit gaps they cannot resolve.
2. These gaps are silently worked around (agent asks a human) rather than systematically fixed.
3. No mechanism exists to discover documentation gaps except human complaints.
4. The system cannot self-improve its own onboarding because failures are not captured.

After this ADR:

• Agents treat documentation gaps as bugs, not inconveniences
• Each failure is a specific, actionable issue (not a vague "docs need work")
• The gap-discovery process is itself documented and repeatable
• Progressive failure creates a natural priority ordering: the most common failures surface first

Proposed protocol

1. Zero-context execution attempts

Periodically (or on significant doc changes), an agent with no project memory attempts to:

• Follow the Quick Start guide end-to-end
• Deploy the solution from scratch
• Submit and complete a task
• Onboard a new repository

The agent follows ONLY what is written — no inference, no "I know this from training data."

2. Failure capture

At each failure point, the agent:

1. Stops — does not attempt to work around or guess
2. Documents — creates an issue with:
   • Which document, which step, which line
   • What was expected vs. what happened
   • What knowledge was missing (the gap)
   • Suggested fix (if obvious)
3. Continues — attempts the next step (if possible) to find additional gaps

3. Knowledge artifacts (interim solutions)

Until documentation meets ADR-004 (tabula rasa standard), agents may create:

• Ephemeral semantic indices of the codebase (call graphs, dependency maps)
• Annotated walkthroughs of successful executions
• "What I learned" summaries after completing a task

These are NOT documentation — they are scaffolding that informs future documentation improvements.

4. Maturity model

Level	State	Agent capability
0	No docs	Agent cannot start; files issue for missing docs
1	Partial docs	Agent follows docs, stops at gaps, files issues
2	Complete docs (ADR-004 compliant)	Agent completes end-to-end without help
3	Self-improving	Agent detects drift between docs and code, auto-files issues

5. Definition of Done (progressive)

"Done" matures alongside knowledge:

• Level 0 done: Issue filed with reproduction steps
• Level 1 done: Code works, tests pass, docs updated for the gap found
• Level 2 done: Code works, tests pass, tabula rasa agent can replicate
• Level 3 done: Code works, tests pass, CI verifies docs match behavior

The self-improvement loop

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 is NOT a one-time effort. It runs continuously because:

• Code changes outpace documentation
• New features introduce new gaps
• Different agent implementations (Claude, Copilot, Kiro) fail at different points

Open questions

1. How often should zero-context execution attempts run? (Weekly? On every release? On doc changes?)
2. Should the "tabula rasa agent" be a dedicated CI job or an ad-hoc activity?
3. How do we prevent issue spam from overly literal failure detection?
4. What's the bar for "the agent cannot work around this" vs. "the agent should figure this out"?

Alignment

Aligns with Documentation and specifications and is a prerequisite for the Agent swarm capability (agents must self-onboard without human hand-holding).

Dependencies

• ADR-004 (RFC: ADR-004 — Tabula rasa documentation standard (zero-context self-sufficiency) #135) — defines the documentation quality target
• ADR-003 (RFC: ADR-003 — Contribution governance for async agents and humans #134) — governance for the issues filed by failing agents

---

• RFC PR: (pending approval)
• Approved by: (pending)
• Reviewed by: (pending)

[orca-ai-admin]

This is a great direction. We built something similar — a self-improvement engine that runs in production continuously:

1. Correction mining: When the human corrects the agent, it gets logged and categorized (not just acknowledged)
2. Structured experiments: Periodically, the system takes a recurring correction pattern and designs an experiment to fix the root cause — with baseline, intervention, measurement, and rollback criteria
3. Graduated enforcement: Successful experiments get promoted to permanent "gates" (shell scripts that enforce the behavior structurally)

15 experiments run so far, 14 kept, 1 still running. One experiment reduced a specific behavioral violation by 97%.

The framework is open-source: Hermit — the self-improvement engine is in scripts/evolution-engine.sh and the correction logging is in self-improvement/.

The key lesson from our experience: progressive failure documentation works, but you also need a pipeline to convert those failure docs into structural fixes. Documentation alone doesn't prevent recurrence — enforcement does.