Version: 0.1
LogDoc Loop is a human-in-the-loop AI-assisted engineering protocol for maintaining a living operational context document during complex technical work.
A LogDoc is the document.
The Loop is the repeated process of:
- attempting a bounded step
- observing the result
- recording the state change
- updating knowns, blockers, risks, and next actions
- creating breakpoints at stable handoff moments
The purpose of the protocol is to keep technical work reproducible, restartable, auditable, and safe to resume after interruption.
LogDoc Loop is designed to support:
- long-running technical iteration
- human-led AI-assisted engineering
- unstable debugging sessions
- project handoff across time
- reproducible builds
- clear risk boundaries
- publication-quality reconstruction
- assistant context restoration
- reduced dependency on chat history
- reduced dependency on human memory
LogDoc Loop is not designed to be:
- a full project management system
- an issue tracker replacement
- a test framework
- a formal proof system
- an autonomous-agent protocol
- a substitute for source control
- a substitute for engineering review
- a substitute for security review
- a substitute for documentation written for end users
A LogDoc may feed into these systems, but it does not replace them.
A living operational context document for a technical project.
It records what is known, what has changed, what has been validated, what remains risky, and what should happen next.
The repeated cycle of:
Attempt → Observe → Interpret → Record → Decide Next Step The loop should continue until the project reaches a breakpoint, milestone, abandonment point, or publication state.
A fact that should be treated as stable until contradicted.
Examples:
- operating system version
- target architecture
- installed tool path
- validated command
- current repo branch
- confirmed dependency version
- known device state
- known unsafe action
Definitive knowns should be explicit, not implied, and should be project-context dependent.
The current active work.
Scope should answer:
- What are we doing now?
- What are we not doing now?
- What counts as success?
- What is intentionally deferred?
Work that may be historically related but is not allowed to drive the current task. This prevents old project goals from contaminating the active plan.
A point where the cost of being wrong increases.
Examples:
- moving from host-side tests to device installs
- deleting generated files
- restoring a device
- publishing compatibility claims
- running destructive commands
- touching production data
- changing security-sensitive configuration
Crossing a risk boundary should require a breakpoint or explicit validation step.
A staged proof sequence.
Instead of jumping from “it compiled once” to “it works,” a validation ladder defines progressive evidence.
Example:
- Source builds.
- Binary is generated.
- Binary has correct architecture.
- Package is generated.
- Package contents inspect correctly.
- Package installs in a safe test environment.
- Runtime behavior is validated.
- Uninstall/recovery path is validated.
A stable handoff snapshot.
A breakpoint records enough context for the project to be safely resumed later.
Breakpoints are mandatory before high-risk transitions and strongly recommended before stopping work.
The latest accurate summary of the project.
Current State should separate:
- validated facts
- partial results
- failures
- blockers
- unknowns
- next actions
Instructions for a future assistant or future session.
This section should include:
- what not to assume
- what not to repeat
- known traps
- preferred working style
- next commands
- important files
- active constraints
A full LogDoc should contain these sections.
Must include:
- project name
- last updated date/time
- owner/operator
- current phase
- current version/checkpoint
Must include:
- active goal
- non-goals
- success criteria
- failure criteria
Must include the stable facts required to avoid repeated rediscovery.
Recommended subsections:
- environment
- target
- repository state
- artifact state
- dependency state
Must separate:
- validated
- partially validated
- not validated
- blocked
- deferred
Must include:
- high-risk actions
- safe assumptions
- recovery paths
- preservation notes
Must include:
- current phase
- immediate next step
- expected result
- versioning data (project and implimentation dependent)
- follow-up if it succeeds
Must record meaningful attempts.
Each entry should include:
- timestamp
- action
- command/change
- result
- interpretation
- next action
Must summarize major events and milestones in order, covering events in series with minimal discontinuity. The timeline should avoid excessive raw logs. It should compress the project history into useful operational memory.
Must define the staged validation path. The ladder should prevent overclaiming.
Must preserve handoff snapshots, with a LogDoc versioning update (v1.12 -> v1.13) Should occur while the project is at a neutral state, or at a milestone achievement
Must include context restoration instructions and the project's last-state and last-neutral working state dependent information.
During active technical iteration, update the LogDoc every 5–15 minutes or after any meaningful state change.
Meaningful state changes include:
- a new error signature
- a fix
- a failed fix
- a changed scope boundary
- a generated artifact
- a validation pass
- a validation failure
- a risk boundary change
- a handoff point
- a stop/pause/branch decision (breakpoint)
The cadence is flexible. The purpose is continuity, not paperwork.
Each major result across all check, hygine, breakpoint, and workflow fields should be classified. Recommended classifications:
- VALIDATED
- PARTIAL
- FAILED
- BLOCKED
- DEFERRED
- UNSAFE
- UNKNOWN
- SUPERSEDED
The result has been tested enough to rely on for the current phase.
VALIDATED
The result has been tested, matching the full claim
PARTIAL
The result shows progress but does not prove the full claim.
FAILED
The attempt did not work.
BLOCKED
The work cannot continue without resolving a dependency, missing fact, or external constraint.
DEFERRED
The work is intentionally postponed.
UNSAFE
The action or result carries unacceptable risk for the current phase.
UNKNOWN
The result is not yet understood, or is lacking context required for a concrete approximation of expected behavior
SUPERSEDED
The result was once relevant but has been replaced by newer information.
A breakpoint within the timeline should include (immediately proceeding current timeline information):
Breakpoint label, LogDoc version: Date/time: Current state: Validated: Not validated: Known risks: Artifacts: Important commands: Next safest action: Do not do next: Safe to pause here:
Breakpoints should be concise but complete.
LogDocs should avoid overclaiming.
Use precise language:
Preferred:
- Host-side package generation is validated.
- Device-side runtime behavior is not validated.
- The current no-op package proves packaging mechanics only.
- The compatibility scope is limited to the tested target.<
Avoid:
- It works.
- Fully supported.
- Production ready.
- Compatible with everything.
- Safe.
- Done.<
Unless those claims are actually proven.
- Perform manual or git-based stale wording scans
- Generate artifact "sanity check" scans for local environment sanity checking pre-push
- Move obsolete artifacts (scripts, documentation, etc) into a centralized git directory (Recommended: /docs/obsolete/*)
- Use sanity scripts and hygiene practices alongside LogDoc breakpoints, milestones, and updates
When a project includes fragile devices, production systems, user data, or irreversible operations, the LogDoc must explicitly separate:
- safe host-side actions
- risky target-side actions
- destructive operations
- recovery paths
- actions that must not be taken casually
High-risk actions should not be hidden inside general task lists.
A LogDoc is not a replacement for Git.
Git records exact source changes. The LogDoc records why changes happened, what was tried, what failed, and what is safe to do next. README files describe the final public state. The LogDoc preserves the working process and handoff state.
For public projects, the LogDoc may be trimmed, redacted, summarized, or split into an attached operations log.
A project developed with LogDoc Loop may publish:
- the final README
- the reproducibility guide
- selected LogDoc excerpts
- a milestone map
- a case study
- a redacted full LogDoc
The raw LogDoc may contain private paths, secrets, device details, passwords, or unsafe commands. It should be reviewed and sanitized before publication.
A minimal LogDoc Loop project should have filled sections for the:
- active goal
- definitive knowns
- current state
- current blocker
- next safe action
- timeline
- breakpoints
A full LogDoc Loop project should have all sections defined in this specification.
LogDoc Loop does not replace engineering judgment.
It is a compression and continuity layer for human-led technical work.
The human remains responsible for deciding:
- what to run
- what to trust
- what to publish
- what to delete
- what to install
- what to claim
- what risks are acceptable