Dev Learning Loop

Dev Learning Loop is a Codex skill that turns meaningful software-development work into evidence-backed personal learning, then verifies that learning later through retrieval and transfer.

It is intentionally not an automatic “write three lessons after every task” prompt. Routine changes are skipped. Durable entries require evidence, transfer value, and a future verification path. Repeated concepts are updated instead of appended.

Why this exists

AI can make developers faster while quietly reducing the amount of reasoning they practice. This project aims for a different outcome: use completed work as authentic learning material while progressively returning responsibility to the user.

The success metric is not notes produced. It is whether the user later makes better independent decisions in a different but related situation.

What it does

• inspects real diffs, failures, tests, benchmarks, and decisions;
• diagnoses the kind of learning gap before choosing an intervention;
• rejects low-value, weakly evidenced, duplicated, or project-local notes;
• tracks capability evidence separately from memory stability;
• schedules retrieval and transfer reviews;
• adapts scaffolding to demonstrated experience;
• keeps learning records project-local and user-correctable by default.

Repository layout

dev-learning-loop/
├── SKILL.md                         Skill entry point and routing
├── agents/openai.yaml               Codex UI and invocation metadata
├── references/
│   ├── educational-foundations.md   Educational constitution and teaching behavior
│   ├── quality-gate.md              Admission and epistemic rules
│   ├── knowledge-model.md           Capability states and record schema
│   ├── assessment.md                Retrieval, transfer, and feedback
│   └── maintenance-and-privacy.md   Consolidation, agency, and privacy
└── scripts/learning_journal.py      Deterministic storage and review CLI

docs/                                Architecture and integration guidance
evals/                               Behavioral evaluation cases
tests/                               Executable unit tests

Install

Clone the repository, then copy or symlink the skill directory into your personal Codex skills directory:

git clone https://github.com/JasonEran/dev-learning-loop.git
mkdir -p "$HOME/.codex/skills"
ln -s "$(pwd)/dev-learning-loop/dev-learning-loop" "$HOME/.codex/skills/dev-learning-loop"

The skill becomes available on the next Codex turn. You can invoke it explicitly:

$dev-learning-loop Review the completed work and capture only durable learning.

Implicit invocation remains enabled. For stronger project-level consistency, add this instruction to the repository's AGENTS.md:

After meaningful implementation, debugging, refactoring, review, or architectural
work is verified, use $dev-learning-loop. Capture only candidates that pass its
quality gate; explicitly skip routine or low-value work.

Quick start

Initialize a project-local learning store:

python3 dev-learning-loop/scripts/learning_journal.py init

Record a candidate. The CLI rejects it unless the configured evidence and quality thresholds pass:

python3 dev-learning-loop/scripts/learning_journal.py record \
  --concept optimistic-locking \
  --title "Prevent lost updates with version checks" \
  --summary "Reject writes based on a stale version." \
  --principle "Validate that the persisted version still matches the writer's observation." \
  --evidence "A concurrency test reproduced and then prevented the lost update." \
  --boundary "Does not coordinate a transaction across multiple resources." \
  --next-transfer-test "Diagnose a stale write in another persistence layer." \
  --state independent-application \
  --epistemic-status verified \
  --novelty 3 --transferability 4 --impact 4 --evidence-strength 4 \
  --duplication 0 --locality 1 --speculation 0

Review due concepts and record the outcome:

python3 dev-learning-loop/scripts/learning_journal.py due
python3 dev-learning-loop/scripts/learning_journal.py review \
  --id optimistic-locking \
  --result success \
  --independent \
  --transfer-context "Applied to an HTTP conditional-update flow"

The store is intentionally plain and inspectable:

.dev-learning/
├── config.json
├── profile.md
├── index.md
├── events.jsonl
└── entries/*.json

Design principles

The skill combines situated learning, adaptive scaffolding, cognitive-load management, self-explanation, retrieval practice, distributed practice, varied transfer, deliberate practice, mastery learning, and self-regulated learning. These are operational rules rather than decorative labels; see educational-foundations.md. The research basis and important limits are summarized in research-basis.md.

The quality gate is deliberately conservative. It is better to skip a task than to pollute long-term memory with plausible-sounding summaries. See quality-gate.md.

Verification

The implementation uses only the Python standard library:

python3 -m unittest discover -s tests -v
python3 /path/to/skill-creator/scripts/quick_validate.py dev-learning-loop

Behavioral eval cases live in evals/cases.json. They focus on observable decisions: skipping mechanical work, refusing unsupported learner claims, merging duplicates, and separating retrieval stability from capability.

Current scope

Version 0.1 provides the standalone skill, educational policy, deterministic local store, quality scoring, semantic-by-concept upsert, review scheduling, audit events, and tests. Semantic embedding-based deduplication, encrypted global stores, UI, and longitudinal outcome studies remain future work.

See ROADMAP.md for the staged path from a reliable local skill to a validated longitudinal learning system.

License

MIT. See LICENSE.