Diagnose config fragment gate failure before retry
After an ownership or expected-bytes gate fails on an application-owned config fragment, run a read-only diagnostic pass to classify the root cause and choose full operation restart versus abort, without refreshing baseline mid-attempt or retrying rename.
Diagnose config fragment gate failure before retry
After an ownership or expected-bytes gate fails on an application-owned configuration fragment, run a read-only diagnostic pass to classify the root cause and choose full operation restart versus abort, without refreshing baseline mid-attempt or retrying rename.
When to use
Use this when a replace operation already failed closed at the ownership gate, expected-bytes gate, publish gate, or empty-baseline classification, and the attempt temporary has been removed without rename.
Reach for this before blindly retrying the same baseline, before treating every byte mismatch as stale input, and before escalating to an operator without evidence.
Adjacent guidance covers running the gates, descriptor binding, empty-baseline branches, publish-gate timing, temp publish, and post-publish verification. This skill covers only the post-failure diagnostic pass that decides what a safe retry requires.
Assumes
The caller already:
- Recorded the operation baseline at attempt start, including presence metadata when the contract requires it.
- Removed the attempt temporary after gate failure.
- Did not rename over the published fragment during the failed attempt.
The failure it prevents
Gate failures surface as generic mismatch or abort messages. Without classification, agents and operators choose wrong next steps:
- Blind retry with the same baseline after a concurrent edit, guaranteeing repeated failure or an unsafe publish if timing shifts.
- Mid-operation baseline refresh to make a failure pass, discarding the fixed baseline contract that gates depend on.
- Mislabeling symlink substitution as concurrent edit, or the reverse, leading to wrong escalation and wasted restarts.
- Immediate rename retry in the same attempt after publish-gate failure, overwriting content that changed legitimately between gates.
Reasoned example (not an executed test): an agent fails the publish gate with expected-bytes mismatch. It refreshes the baseline from the newly observed bytes and retries rename in the same attempt, publishing over a hotfix an operator applied during temp preparation. The diagnostic pass was skipped, so nobody recorded that the observed bytes differed from the operation-start baseline because of concurrent edit rather than stale capture.
Diagnostic procedure
Run read-only. Do not write, rename, truncate, or chmod during this pass.
- Open the managed directory as a directory descriptor when the contract allows. Open the fragment relative to that descriptor with no-follow semantics. If the final component is a symlink, record entry type as symlink and stop classifying as a regular-file concurrent edit.
- Capture observation snapshot from the open descriptor:
- entry type (regular file, symlink, absent, directory, other)
- owner identity and mode
- byte length
- raw bytes or digest
- optional inode or generation token only if the application contract exposes one; do not invent generations
- Compare snapshot to the operation-start baseline (not a freshly chosen baseline):
- ownership or mode drift versus contract
- presence transition (absent to present, present to absent)
- byte length change
- digest mismatch
- Compare snapshot to the failure context recorded by the gate that aborted:
- whether failure was at ownership gate, expected-bytes gate, empty-baseline branch, or publish gate
- whether descriptor-bound fstat passed before bytes disagreed (same-inode mutation signal)
- whether separate path stat and path read were used (path-string split signal)
- Assign one primary category using the decision table below. Secondary notes are allowed but must not override the primary category for retry policy.
- Choose next action from the category policy. Never rename during diagnosis.
Classification decision table
All rows are reasoned outcomes, not executed test results.
| Observation versus operation-start baseline | Gate context | Primary category | Safe next action |
|---|---|---|---|
| Entry type is symlink where regular file expected | any gate | symlink_substitution | Abort attempt; escalate for managed-directory integrity; full restart only after contract owner repairs the name |
| Ownership or mode differs from contract | ownership gate | ownership_drift | Abort; escalate; do not retry until contract metadata restored |
| Regular file; digest differs; descriptor-bound fstat had passed | expected-bytes or publish gate | concurrent_edit | Full operation restart required; capture fresh baseline at new attempt start; do not reuse old baseline |
| Regular file; digest differs; separate path stat and path read were used | expected-bytes gate | pathstringsplit_suspected | Full restart using descriptor-bound gates only; treat prior failure as potentially unreliable |
| Regular file; digest differs; baseline captured long ago with no concurrent writer evidence | expected-bytes gate | stale_baseline | Full operation restart with fresh baseline capture before any temp write |
| Present zero-length file; baseline presence was absent | empty-baseline branch | unexpectedemptypresent | Full restart after infrastructure or operator resolves placeholder; capture baseline that matches contract create semantics |
| Present zero-length file; baseline presence was must_exist with non-zero length | empty-baseline branch | concurrent_wipe | Abort; escalate; do not publish until operator confirms data loss scope |
| Absent path; baseline required present | any gate | baselinepresentnow_absent | Abort; escalate for deletion or repointing |
| Observation matches baseline but gate still failed | any gate | gateimplementationmismatch | Escalate for tooling bug; do not retry blindly |
Category policies
concurrentedit, stalebaseline, unexpectedemptypresent, pathstringsplit_suspected
- Require a full operation restart: new attempt identity, new exclusive temp name, new baseline capture at restart start, then rerun all gates including publish gate.
- Do not refresh baseline inside the failed attempt.
- Do not retry rename in the failed attempt.
symlinksubstitution, ownershipdrift, baselinepresentnowabsent, concurrentwipe
- Abort and escalate. Read-only diagnosis may be attached to the report.
- Do not restart until the contract owner or operator resolves the integrity condition.
gateimplementationmismatch
- Stop automated retry loops. Preserve observation snapshot and gate context for maintainer review.
Worked example: publish gate mismatch misread as stale baseline
Reasoned example (not an executed test).
Setup. Baseline captured non-empty bytes at operation start. Agent writes temp, runs publish gate immediately before rename. Publish gate observes different non-empty bytes. Agent aborts and removes temp.
Diagnostic pass. Reopen with no-follow semantics. Observation snapshot shows regular file, matching ownership, digest equal to publish-gate observation, digest not equal to operation-start baseline.
Classification. concurrent_edit (baseline fixed at start; target changed during temp preparation).
Wrong action avoided. Refreshing baseline to the publish-gate bytes and retrying rename in the same attempt would publish over the intervening edit without a new operator decision.
Correct action. Full operation restart; operator decides whether the replacement intent still applies against the new on-disk bytes.
What this does not provide
- Not a substitute for running gates. Diagnosis follows failure; it does not replace ownership, expected-byte, publish, or post-publish verification steps.
- Not post-publish mismatch recovery. When rename already occurred and verification failed, use post-publish verification failure policy and operator escalation; do not use this skill to invent rollback.
- Not writer serialization. Diagnosis does not acquire locks or leases.
- Not empty-baseline branch definition. Presence branches remain in empty-baseline guidance; this skill consumes their classified categories when present.
Failure policy
- Never mutate the fragment or managed directory during diagnosis.
- Never refresh the operation-start baseline mid-attempt to force a retry.
- Never retry rename in the same attempt after a publish-gate failure.
- Never classify concurrent_edit when entry type is symlink unless the contract explicitly treats symlinks as regular-file equivalents.
- Never treat diagnostic read bytes as authorization to publish; restart gates are still required.
Claims and evidence
The diagnostic sequence and decision table follow from maintenance conversation thrdih-OceC1FecAn1tkspWtg sequence 1 (descriptor gate improvement B) and thrZbdD3NWrGMZZxxE2KWI-XQ sequence 1 (post-failure restart checklist deferred by empty-baseline guidance). The publish-gate misread example is a reasoned timeline only; no filesystem or concurrency tests were executed for this skill.