Evidence store
Preserves typed records, feature IDs, categories, timestamps, and outcomes.
db/agent_log.sqlite3Meta-layer / Governed self-learning
The team improves by earning rules.
One run creates an anecdote. Repeated evidence creates a candidate pattern. A human-approved proposal becomes policy. Future outcomes determine whether that policy deserves to stay.
Self-learning
evidence → proposal → approval → policy → measured next run
Pattern laboratory
What did the evidence repeat?
3+ repeated decisions · consistent rationale · outcomes confirmed
Promote a recurring decision into a principle.
If agents repeatedly reach the same sound decision, stop charging every future run to reason through it again.
- Target
- Relevant agent definition
- Proposal
- Exact principle text + destination section
- Authority
01 / The governance boundary
Self-learning is not self-rewriting.
The system may notice patterns and draft changes. It may not silently alter the rules that will govern future agents.
Hard boundary
The Log Analyst cannot modify agent definitions, application code, or the log database. It writes only to docs/agent-analysis/.
02 / The complete learning cycle
A rule is a hypothesis with a longer half-life.
The loop closes only when the changed policy runs again and its effects become new observed evidence.
- 01
Run
Specialists ship features under the current policy.
- 02
Record
Decisions, findings, gaps, and outcomes accumulate.
- 03
Analyze
The analyst compares runs, roles, features, and quality.
- 04
Propose
Each pattern becomes exact text and an explicit destination.
- 05
Approve
A human chooses which proposals become policy.
- 06
Implement
The builder changes only the approved agent or skill.
- 07
Observe again
Future runs test whether the rule reduced effort or failure.
New evidence returns to the same recorder↺
03 / Six learning signals
Different patterns should change different assets.
The important question is not merely “what repeated?” It is “where should this knowledge live so it prevents the next failure?”
Repeated sound decision
A choice made three or more times with consistent rationale and strong outcomes becomes a standing principle.
Change: agent guidanceRepeated rejected alternative
An option rejected at least twice for the same reason becomes an explicit anti-pattern.
Change: agent prohibitionsRepeated upstream silence
Agents keep inventing the same missing fact because a brief or spec template failed to require it.
Change: artifact-format skillPrediction did not survive contact
The observed result differs materially from the expected outcome, exposing a faulty assumption.
Change: reasoning guidancePractice predicts stronger work
A behavior appears in high-quality runs and is absent from weaker runs.
Change: agent processFinding repeats across features
A review category appears across three or more features and can be prevented before implementation.
Change: new or expanded skill04 / Confidence calibration
Do not promote anecdotes into doctrine.
Thresholds are deterministic filters. Whether the pattern is causally meaningful still requires analysis and human judgment.
| Evidence | Confidence | Allowed action |
|---|---|---|
| One occurrence | Insufficient | Record under “requires more data.” Do not propose a rule. |
| Two consistent occurrences | Medium | Surface as a candidate. Defer unless the risk justifies earlier action. |
| 3+ consistent occurrences | High | Propose exact policy text, especially when outcomes confirm it. |
| Finding across 3–4 features | Skill candidate | Define prevention content; one more feature strengthens the case. |
| Finding across 5+ features | High-confidence skill | Recommend building the prevention skill now. |
| Clear expected/observed mismatch | Direct correction | Correct the faulty assumption, with evidence attached. |
05 / Human approval laboratory
A proposal must be specific enough to reject.
Vague recommendations cannot be governed. A useful proposal names the evidence, exact text, destination, confidence, and expected effect.
Require collection-size expectations in architecture specs.
- Evidence
N+1findings in 4 features; 3 specs omitted expected collection size.- Target
skills/architect-spec-format/SKILL.md· Behavioral Constraints- Exact addition
- “For every collection view, state expected cardinality, pagination behavior, and query-count constraint.”
- Expected effect
- Move performance reasoning before implementation; reduce repeated reviewer catches.
06 / Cadence
Analysis is triggered by evidence volume, not a calendar.
The feature pipeline checks how many completed cycles have accumulated since the last dated analysis report. It nudges; it never launches the analyst automatically.
0–9 cyclesKeep collecting
Too little cross-feature signal for a broad analysis pass.
10–14 cyclesWorth a run
Mention that the Log Analyst has enough new evidence.
15+ cyclesPast the window
Call out that analysis is overdue, without blocking delivery.
Why it is a nudge
Learning is valuable but not a feature-delivery gate. Automatically interrupting every pipeline would turn compounding into friction.
07 / What this system refuses
Guard against performative learning.
A learning loop compounds only when it changes future behavior for a traceable reason.
Prompt edits from one bad run
That is reaction without recurrence evidence.
An agent rewriting itself
That removes the independent governance boundary.
A dashboard of activity counts
Usage is not improvement unless it informs a decision.
Adding a skill for every finding
Policy bloat increases context cost and creates contradictions.
Applying every analyst proposal
Confidence is evidence quality, not authority.
Never recording outcomes
Without observed results, the system cannot test its own expectations.
08 / Build it portably
Preserve the governance loop; replace the domain policy.
The schema, thresholds, analyst constraints, proposal format, and approval gate can travel to any language. The rules being proposed must remain native to that ecosystem.
Inspect the Log AnalystEvidence grammar
Runs, decisions, findings, reflections, outcomes.
Pattern thresholds
Minimum recurrence and confidence calibration.
Human approval
Selective acceptance before mutation.
Domain doctrine
Rails principles become the target ecosystem’s judgment.