Turning a Long-Term Learning Roadmap into an Evidence-Driven Feedback Loop

A long learning roadmap can look complete while saying very little about what the learner can do today. A calendar can list Linux, containers, cloud infrastructure, and reliability engineering for the next eighteen months, yet still lose the information needed to answer practical questions:

• Was yesterday's task completed or merely read?
• Can the learner explain the result without following the same steps?
• Which weak topic should return this week?
• Should next week's load shrink, stay stable, or grow?

These questions led to a different implementation: treat the roadmap as a stateful feedback loop. The curriculum defines the intended sequence, daily plans select a bounded slice, submitted evidence changes progress state, and weekly review adjusts future work within explicit limits.

Why a calendar is insufficient

The first design used a long sequence of weekly topics. It was useful for scope, but it had no durable answer for interruptions, repeated scheduler runs, weak understanding, or missed days. Regenerating a plan could overwrite unfinished work. Marking a task complete from a chat statement could advance the learner without proof. Keeping the original pace after a difficult week could turn the remaining plan into an accumulating backlog.

The root cause was that the calendar had been asked to represent both intent and observed progress. Those are different kinds of data:

• the curriculum records prerequisites, phase gates, and the desired order;
• progress state records generated plans, task status, time spent, evidence, mastery, review dates, and blockers;
• review logic decides how observations may affect later workload.

Once these responsibilities were separated, missed work no longer required rewriting the roadmap or pretending the original date still represented readiness.

Make daily planning idempotent

A scheduled coach may run more than once for the same date. Daily planning is idempotent when repeating that date restores the same saved result. The planner therefore uses the date as a stable plan identity and follows a restore-before-create rule:

1. look for an existing plan for the requested date;
2. return it unchanged when it exists;
3. otherwise select tasks within that day's time budget;
4. persist both the plan and its task records before returning.

This prevents a retry from replacing unfinished tasks or creating a second set of work. Weekday and weekend budgets can differ, but they remain inputs to first creation; they do not justify silently rewriting an existing day.

Idempotency also makes a missed scheduled run ordinary. The learner can start the coach manually and receive the same durable plan rather than a guessed backfill or a new schedule branch.

Bind completion to evidence

Task status is useful only when its meaning is stable. The completion command requires an evidence path for finished work. Acceptable evidence depends on the task: command output, code, tests, a runbook, or a recorded demonstration may be appropriate. A claim in chat alone does not change a task to complete.

Mastery is recorded separately from completion on a zero-to-five scale. A successful command can prove that the procedure ran, while an independent explanation or variation is still required for a high score. This distinction keeps execution evidence from being mistaken for understanding.

The score also schedules retrieval:

• scores from zero to two return within forty-eight hours;
• a score of three returns after seven days;
• stronger results can remain governed by later phase reviews.

The exact intervals are policy choices. The reusable mechanism is to save the next review date in structured state so that weak topics compete for future plan capacity instead of disappearing into prose notes.

Adapt load without weakening the gate

Weekly review compares planned work with recorded outcomes. In the implemented policy, completion below seventy percent reduces the following week's load by twenty percent. Completion above ninety percent may increase load by at most ten percent, and only when average mastery is at least four and no blocker remains.

These bounds keep adaptation explainable. They also separate pace from readiness. A slower week may reduce volume, but it does not lower a prerequisite score or remove a portfolio requirement. When evidence is insufficient, the timeline extends.

Blockers are classified before the plan changes. A knowledge gap calls for reteaching, an environment failure calls for troubleshooting, a time constraint calls for smaller work, and an oversized task calls for decomposition. Applying the same remedy to all four would hide the real constraint.

Keep publication and cost outside routine progress

Learning records can contain private career information, machine paths, accounts, or cloud details. Public progress therefore passes a separate publication gate and privacy scan. Routine coaching may update local state, but committing or pushing a daily record requires an explicit current instruction and path-scoped staging.

Potentially billable cloud labs use another boundary: estimate cost, confirm a budget alarm, obtain approval, and prepare teardown before creating resources. A learning scheduler should never turn a study reminder into an unattended spending decision.

Verification

The public reference implementation packages the curriculum, JSON Schemas (machine-readable rules for file structure), planner, review logic, privacy checks, and tests in one repository. Its tagged release covers seventy-eight weeks and passed CI at the exact release commit. The automated checks verify that:

• generating the same date twice restores the original plan;
• weekday and weekend time budgets are enforced;
• completion requires evidence;
• weak and medium scores schedule the expected review dates;
• low, normal, high, and blocked weeks choose bounded load changes;
• the curriculum and progress files satisfy their schemas;
• the public tree passes privacy and Markdown-link checks.

The source repository, tagged release, and matching CI run keep those claims reviewable.

Lessons and limits

An evidence-driven coach still cannot prove employability from task counts. It can make the path auditable: what was planned, what was demonstrated, what remains weak, and why the next load changed. Hiring outcomes, curriculum relevance, and the quality of submitted evidence still need human judgment and periodic external review.

The durable design is a small control loop: preserve curriculum intent, restore daily work deterministically, require evidence before state advances, schedule weak knowledge to return, and adjust volume without relaxing readiness gates.