112 lines
6.9 KiB
Markdown
112 lines
6.9 KiB
Markdown
# Execution records and diagnostic workflow
|
|
|
|
This document governs development records, not application logging. It supplements
|
|
[the implementation order](IMPLEMENTATION.md) and [agent instructions](../AGENTS.md).
|
|
Product requirements, independent review and acceptance gates are unchanged.
|
|
|
|
## Record boundaries
|
|
|
|
| Record | Purpose | Contents |
|
|
| --- | --- | --- |
|
|
| [PLANS.md](../PLANS.md) | Current execution contract and resume point | Scope, acceptance checklist, task state/owner, open findings, concise closed-finding disposition, latest applicable evidence, limitations and next action. |
|
|
| `docs/diagnostics/milestone-N.md` | Investigation notebook, created only when needed | Failed attempts, hypotheses, bounded diagnostics, observations, cause and repair verification. |
|
|
| `docs/evidence/milestone-N.md` | Reproducible evidence report, created when evidence no longer fits a concise plan table | Exact commands, source/build identity, environment, outcomes, review disposition and acceptance mapping. |
|
|
| `docs/history/` | Preserved superseded records | Historical snapshots with an explicit non-current notice and a link back to the plan. |
|
|
|
|
The plan is a current snapshot, not an append-only diary. Do not copy worker
|
|
reports or full diagnostic sequences into it. Keep the detailed report in one
|
|
place and link it. Evidence and diagnostic reports never override the plan's
|
|
scope or the specification. Read only the relevant investigation/report when
|
|
resuming; reading all historical logs is not a prerequisite for implementation.
|
|
|
|
## Updating the plan
|
|
|
|
The coordinator updates a task row in place when its result, owner, next action,
|
|
review disposition or blocker changes, and before handoff. A failed command alone
|
|
does not need a plan entry unless it changes current status or invalidates evidence.
|
|
For an active failure keep one concise entry: affected behavior, known facts,
|
|
owner, next discriminating check and acceptance impact. Replace it as facts change.
|
|
|
|
Keep the milestone register, milestone status/outcome and top-level resume point
|
|
consistent in the same edit. Use the existing lifecycle states; distinguish a
|
|
repairable defect (`needs_changes`) from an unavailable prerequisite (`blocked`).
|
|
Task completion does not imply milestone acceptance. Closed findings retain their
|
|
stable ID, effect, final resolution and review/evidence reference; intermediate
|
|
repair attempts belong in diagnostics. Superseded passing runs are historical,
|
|
not additional proof for the current revision.
|
|
|
|
Aim for at most one short paragraph per task/finding and one row per evidence
|
|
scope. This is a readability target, not permission to omit acceptance criteria,
|
|
required evidence, unresolved findings or safety constraints. If detail exceeds
|
|
that target, move the detail to the appropriate linked report.
|
|
|
|
## Investigating failures
|
|
|
|
1. Classify the failure: prerequisite, fixture/transport, application behavior,
|
|
assertion, or currently unknown. Do not assume the application or fixture is
|
|
correct before checking.
|
|
2. Record a concrete hypothesis and the smallest bounded check that distinguishes
|
|
it from alternatives. Reuse the same task/finding ID across attempts.
|
|
3. Run that check and record the observation. Retry unchanged commands only for
|
|
an evidenced transient condition or deliberate repeatability check; record why.
|
|
4. After two failed repair attempts for the same symptom, reassess the cause and
|
|
task boundary before another expensive full run. Obtain a focused independent
|
|
review or reduce to a minimal reproduction when useful. This is an escalation
|
|
of investigation, not an arbitrary acceptance cutoff or a reason to ask the
|
|
user to resolve routine implementation choices.
|
|
5. Repair the cause, run focused checks, then rerun affected integration behavior.
|
|
Rebuild the container driver when its inputs changed; reuse a compatible pinned
|
|
builder/cache. Do not run the full Rust gates for every diagnostic edit. Run
|
|
them at the required completion gates and again if subsequent changes invalidate
|
|
them, following [TESTING.md](TESTING.md).
|
|
6. Review the actual repair and affected behavior independently. Consolidate the
|
|
plan to the final result, remaining uncertainty and next action.
|
|
|
|
A diagnostic entry contains: ISO timestamp with offset; task/finding ID; symptom;
|
|
hypothesis; exact safe command or reproduction reference; observed result; cause
|
|
if established; next action or closure/evidence reference. Record only useful
|
|
redacted excerpts. Raw logs, secrets, configuration payloads, private keys and
|
|
working backups must not be committed. An agent stall or usage limit needs a
|
|
brief handoff note only when it affects ownership or the next action.
|
|
|
|
## Evidence and handoff
|
|
|
|
An evidence entry identifies:
|
|
|
|
- Task/criterion and run timestamp with offset.
|
|
- Tested commit plus dirty-state description, or a reproducible fingerprint of
|
|
relevant tracked/untracked source inputs; identify the built artifact and its
|
|
source inputs when a separate container binary is used. A commit alone does
|
|
not identify a dirty working tree. Never fingerprint secret-bearing data into
|
|
a report or claim a source identity that was not captured.
|
|
- Exact command, toolchain/target and required environment or immutable image
|
|
identity, excluding secrets. Mark missing historical identity as unavailable.
|
|
- Actual outcome: exit/result counts, fixture versus Alpine versus VM scope,
|
|
cleanup outcome, limitations and which later edits invalidate the evidence.
|
|
- Independent reviewer disposition and remaining findings where applicable.
|
|
|
|
Do not manufacture missing evidence when migrating old records. Carry forward
|
|
reported results as historical evidence and state whether they were rerun.
|
|
Before accepting a milestone, verify the integrated files, close actionable
|
|
findings, run required gates on that revision and update the acceptance mapping.
|
|
|
|
A handoff consists of current task/state/owner, open issue, latest applicable
|
|
checks, environment prerequisites and one concrete next action. Link diagnostics
|
|
only if needed to avoid repeating an investigation. It must be possible to resume
|
|
from the current plan without reconstructing chronology.
|
|
|
|
## Migration and ownership
|
|
|
|
Preserve the old record in `docs/history/` before compacting existing diagnostic
|
|
history. Keep scope, acceptance criteria, stable finding IDs, final outcomes,
|
|
limitations and source links. Clearly label contradictory historical statuses as
|
|
superseded. Migrate older accepted milestones when they need maintenance; do not
|
|
rewrite their acceptance merely for uniform formatting.
|
|
|
|
The coordinator owns PLANS.md and evidence consolidation. Assign a diagnostics
|
|
file to one writer at a time, or have workers return concise entries for the
|
|
coordinator to integrate. Include these record boundaries in dispatch briefs;
|
|
workers still report actual checks and unresolved issues. New agent configuration
|
|
may not affect an existing session: supply this document explicitly at its next
|
|
authorized dispatch/handoff. Do not message other chats without user authorization.
|