-
Notifications
You must be signed in to change notification settings - Fork 95
Adaptive Control and Drift Score
Adaptive control is the workflow's closed-loop correction system. It exists because large implementation plans often become less accurate as execution reveals new complexity.
Spec-Driven Develop measures plan-vs-reality drift after each task and triggers corrective action when the plan no longer matches the codebase.
| Control Theory Term | Workflow Meaning |
|---|---|
| Plant | The codebase being changed |
| Set point | The Phase 2 confirmed task definition and S.U.P.E.R principles |
| Controller | The Spec-Driven Develop workflow |
| Actuator | The task executor agent or agents |
| Sensor | Post-task telemetry collection |
| Error signal | drift_score |
After each task, the agent records three signals.
The workflow compares estimated effort with actual effort:
| Effort | Meaning |
|---|---|
| S | Under 30 minutes, no unexpected issues |
| M | 30 minutes to 2 hours, minor surprises |
| L | 2 to 4 hours, significant unexpected complexity |
| XL | More than 4 hours or fundamental rethinking |
Only underestimated effort increases drift.
If a task was supposed to improve S.U.P.E.R architecture quality but does not improve it, that counts as drift. Regression is more serious than neutral progress.
The agent counts dependencies not listed in the task plan:
- Unexpected files that needed edits.
- Missing prerequisite tasks.
- External API or library changes.
- Hidden coupling discovered during implementation.
task_drift =
max(0, effort_delta)
+ 1 if S.U.P.E.R improvement was expected but did not happen
+ min(unplanned_dependencies, 2)
The cumulative drift_score is the sum of completed task drift in the current phase.
Thresholds are based on the number of tasks in the phase:
| Drift Level | Threshold | Response |
|---|---|---|
| Mild | At least 20% of phase task count | Annotate the next task with a warning |
| Significant | At least 40% | Halt and re-decompose remaining tasks |
| Severe | At least 60% | Return to Phase 2 for scope re-evaluation |
For a phase with 10 tasks:
- Annotate at 2 drift points.
- Replan at 4 drift points.
- Rescope at 6 drift points.
Mild drift means the plan is still viable but the next task deserves caution.
In GitHub modes, the workflow can add a warning label and comment to the next pending Issue.
In local-only mode, it records a warning in the progress file.
Significant drift means the remaining task breakdown is probably inaccurate.
The workflow should:
- Halt current execution.
- Mark the remaining unstarted tasks as superseded.
- Re-enter Phase 3 for the remaining scope.
- Use completed task telemetry to improve new estimates.
- Keep completed tasks and their history.
Severe drift means the original scope or strategy may be wrong.
The workflow should:
- Halt execution.
- Summarize what changed.
- Return to Phase 2.
- Ask the user to re-confirm scope and priorities.
- Re-plan the remaining work after confirmation.
| Mode | Storage |
|---|---|
| GITHUB_FULL | Milestone description plus Issue comments |
| GITHUB_STANDARD | Milestone description plus Issue comments |
| LOCAL_ONLY | docs/progress/MASTER.md |
Most project plans degrade when reality disagrees with estimates. Adaptive control gives the agent a rule for stopping, replanning, and asking for scope confirmation instead of continuing through a stale plan.