Debugging SOP

Use: Apply this Standard Operating Procedure (SOP) whenever diagnosing or fixing a defect, failure, regression, crash, incorrect result, integration problem, performance problem, flaky test, packaging failure, or unexpected runtime behavior in Arcane OS. Ordinary diagnosis uses read-only inspection. Reproduction, manual experiments, tests, checks, rebuilds, retests, security investigation, or release verification occur only when the user expressly authorizes that exact work or when required for a selected output.

Preserve complete errors, logs, diagnostics, requests, responses, messages, documents, model output, and tool output. Never truncate or replace them with byte counts, hashes, digests, checksums, sizes, or verification receipts. Credentials, secrets, protected operational data, and explicit privacy choices remain protected at their exact owners. Optional security, hardening, provenance, signing, trust, freezing, restrictive admission, and fail-closed work requires the user's exact authorization; ordinary secure: false functionality remains available.

Meaning of ASS-U-ME

ASS-U-ME is a warning, not a list of invented steps:

Do not assume. An assumption makes an ass out of you and me.

Debugging starts with facts. Do not assume that the report is correct, the expectation is correct, the code is wrong, the environment is current, a dependency is working, or a proposed cause is relevant. Verify each one.

What a bug is

A reported bug is usually a difference between an observed result and an expected result.

That difference does not prove the implementation is defective. The expectation may be incomplete, outdated, misguided, mistaken, or wrong. The observation may also be misunderstood, stale, or taken from a different environment. The first job is therefore to verify both sides of the comparison.

Use this statement:

Under [specific conditions], I observed [result]. I expected [result] because [verified requirement, contract, design, or user instruction].

If the expectation has no verified basis, do not change the system to satisfy it. Clarify the intended behavior first.

Governing rules

1. Work one proven step at a time.
2. Separate facts, expectations, questions, and possible explanations.
3. Reproduce before changing anything only when runtime verification is expressly authorized and it is safe to do so.
4. Preserve the failing state and evidence before resetting, rebuilding, restarting, clearing, or repairing it.
5. Inspect the exact point where reality first differs from the verified expectation.
6. Change only one independent variable at a time.
7. Use a manual correction only when that diagnostic experiment is authorized and useful.
8. Rebuild or retest only when verification is expressly authorized or required for a selected output.
9. Never call a disappearing symptom a root cause.

One step at a time does not mean one file at a time. A coherent fix may require coordinated edits. It means that every action answers one question and produces a result that can be interpreted before the next action is chosen.

Rapid-development path

For ordinary local development:

1. verify the expected behavior from a contract, test, design, or explicit instruction;
2. preserve the complete available error, log, input, and before-state;
3. inspect the first boundary where observed behavior differs;
4. for a diagnosis-only request, stop after inspection and report the observed cause or remaining uncertainty without changing source or state;
5. for an authorized fix, change the smallest coherent cause and update useful regression-test source without executing it; and
6. reproduce, rebuild, retest, or run a check only when the user expressly authorizes verification or a selected output requires it.

Manual state correction is recommended when it usefully proves the boundary, but it is not ceremony that must be invented for a simple deterministic source defect. A full clean environment is likewise reserved for dependency, packaging, persistent-state, platform, integration, promotion, or release failures where environment state can change the result.

Use the optional extended stages below only within the same explicit authority.

Prevent late repairable failures

A repairable checkout prerequisite first discovered after dependency installation, signing, compilation, or package generation is a defect in the setup boundary even when the downstream validator reports the facts correctly. Examples include unresolved Git LFS pointers, a missing supported tool, an unsafe checkout path, or a known checkout migration.

For that class of failure:

1. preserve the downstream error and identify the earliest point at which the prerequisite could have been proven;
2. manually correct that one prerequisite and rerun the original operation to prove the causal boundary;
3. put the permanent inspection or repair in the canonical repository-root setup before expensive work begins;
4. make every interactive first-run or missing-build launcher converge on that setup;
5. keep later functional error reporting focused on the distinct downstream operation; do not add byte, hash, receipt, provenance, signing, trust, or restrictive-admission gates without exact user authorization.

Do not fix one named asset when the observed cause applies to an inventory, and do not move application-specific behavior into Arcane OS. Arcane OS owns the generic published ARCANE_APP_RELEASE.json inventory contract; the owning application owns its source, adapters, content, and behavior.

Diagnose performance and apparent hangs

A setup, build, package, test, model, app, or runtime path that appears hung or takes unexpectedly long is a debugging problem, not merely a progress-display problem. Inspect its work amplification without executing verification unless authorized. Preserve the available timeline and record operation count, elapsed time, CPU/disk/network activity, and emitted progress events without byte accounting. State the cardinality and loop multiplier, then classify each expensive operation as invariant, necessarily per item, reusable, or batchable.

Find the first boundary that repeats work without a changing functional input. Hoist invariant downloads, extraction, compilation, model pulls, service setup, and other shared preparation; batch compatible work. Give cached work an honest functional invalidation rule. Arcane OS-owned work must not repeat per app, and app-owned compilation or behavior-test source remains in that application.

For a Microsoft NT WebView2 page whose Network panel shows a long Stalled or connection-start phase before an otherwise immediate local response, inspect the virtual-host name before attributing the delay to package work. Microsoft documents that a .local top-level domain can delay SetVirtualHostNameToFolderMapping navigation. Arcane's packaged host is https://os.arcane; the legacy https://arcane.local name is not an accepted test configuration. Measure the native executable, not only a development web server. The current host does not migrate legacy origin storage, so preserve the WebView2 profile untouched and expect https://os.arcane to have separate origin-scoped state.

Eliminate redundant scans and operations before adding a spinner, percentage, or heartbeat. Then preserve the phase, current item, completed/total item count, elapsed time, and an honest ETA when one can be computed without byte accounting. Record each intentionally repeated expensive operation, its multiplier, why it cannot be batched or reused, and its elapsed cost.

Diagnose the responsiveness invariant

Record timestamps for request receipt, first visible UI or CLI acknowledgement, worker start, first progress event, each heartbeat, cancellation request, and completion or failure. A process existing in Task Manager is not proof that its interface acknowledged or remained responsive.

Inspect the foreground call chain for synchronous network, disk, compilation, process, or model waits before UI creation or between event-loop turns. An async/await function that invokes blocking work synchronously has not isolated that work. CPU-bound or blocking APIs belong in an event-driven background worker, genuine asynchronous I/O stays asynchronous through the stack, concurrency is bounded with backpressure, and every task has an owner that observes its error.

When runtime verification is expressly authorized, reproduce with a deliberately slow but bounded dependency and observe acknowledgement, progress, cancellation, retry/resume, and surfaced worker failure. Unobserved fire-and-forget work is prohibited.

Available investigation stages

Begin with preservation and inspection:

Preserve -> Inspect -> diagnosis-only stop

An authorized fix may continue from inspection to isolation and the smallest source correction without runtime verification. Reproduce, manually correct, rebuild, or retest only when the user separately authorizes that verification or a selected output requires it. Do not invent verification authority because a likely solution seems obvious.

1. Reproduce

When runtime reproduction is authorized, perform the exact action that is reported to fail.

Record:

• the precise action, input, command, route, or workflow;
• the observed result, including exact error identity where available;
• the claimed expected result;
• the app, component, module, entity, version, host, browser, configuration, and data involved;
• whether the result is consistent, intermittent, timing-dependent, or environment-dependent.

Do not improve, simplify, or substitute a different reproduction before proving the original one. If it cannot be reproduced, say so and improve observability; do not make a speculative fix.

Record: The original behavior was observed, or reproduction was not authorized or not currently possible.

2. Preserve

Preserve the evidence and failing state before an action can erase or alter them.

As applicable, save:

• the relevant error, log, screenshot, response, stack, state, or data;
• the exact version and configuration;
• cache, storage, process, network, package, and service state;
• the smallest useful before-state for later comparison;
• unrelated user work in the worktree.

Do not clear a cache, restart a service, reinstall a dependency, rebuild a package, migrate data, delete a record, or reset the environment until the original state is captured. Those actions are experiments, not housekeeping.

Gate: A later reviewer can tell what failed before the investigation changed it.

3. Inspect

Inspect the system as it exists. Prefer read-only checks first.

Verify:

• what code and assets are actually running, not merely what is on disk;
• the input entering the failing operation;
• the output leaving it;
• state immediately before and after it;
• the applicable requirement, interface contract, design decision, or user instruction;
• whether the expectation is correct for this version, environment, and input.

Label every statement as one of:

• Observed fact — directly seen or measured;
• Verified expectation — supported by a requirement, contract, design, or explicit user instruction;
• Question — not yet known;
• Possible explanation — something to test, never a fact.

Do not convert a possible explanation into a conclusion through confident wording.

Gate: The observed behavior and the verified expectation are both known. If the expectation was wrong, correct the expectation or documentation and stop treating the implementation as defective.

4. Isolate

Find the first boundary or step where the observed state differs from the verified expectation.

Move through the workflow one boundary at a time. At each boundary:

1. identify the expected input and output;
2. observe the actual input and output;
3. change or test one independent variable only;
4. inspect and record the result before continuing.

Useful boundaries include user action, event, component, module, entity, storage layer, request, response, service, host bridge, package, and cache.

Do not apply several plausible fixes together. Do not refactor, upgrade dependencies, reset state, and change configuration in the same experiment. A result with several changed variables does not establish which change mattered.

Gate: The first incorrect transition is identified closely enough that a manual correction can test the expected outcome.

5. Manually correct for diagnosis

Only when a state-changing diagnostic experiment is expressly authorized, manually place the isolated boundary into the state the system was expected to produce, when safe and practical.

Examples include supplying the verified input, correcting one record in a disposable copy, invoking the expected operation directly, loading the known-current asset, or performing the missing transition through a diagnostic interface.

The manual correction must be:

• narrow;
• reversible or performed on disposable data;
• recorded exactly;
• limited to the isolated variable.

This is a diagnostic experiment, not the final repair. If a manual correction would be destructive, unsafe, affect real users, or require new authority, stop and request direction.

Gate: One controlled manual change has been made and nothing unrelated was changed with it.

6. Manually verify

Repeat the affected step with the manual correction in place.

Compare the result to both:

• the preserved failing baseline; and
• the verified expectation.

Classify the result:

• Proven useful: the exact failure is corrected and the predicted downstream behavior occurs;
• Disproven: the exact failure remains or the predicted behavior does not occur;
• Inconclusive: the result cannot distinguish the proposed mechanism from another cause.

If disproven or inconclusive, undo the diagnostic change when appropriate, return to Inspect or Isolate, and take one new step. Do not leave a failed experiment in place while stacking another one on top.

Gate: The manual correction has demonstrated what the implementation must do. A temporary disappearance after a restart, retry, delay, cache clear, or broad rebuild is not enough.

7. Fix the code

When the user authorizes a fix, change the implementation to correct the cause supported by inspection. Manual or runtime verification is not a prerequisite when it was not authorized; report that boundary honestly.

The fix must:

• address the isolated cause rather than hide the symptom;
• be the smallest coherent correction;
• preserve unrelated behavior and user work;
• include focused regression-test or contract-check source where useful, without executing it automatically;
• name every new or modified function and callback so failure stacks identify the operation and its exit condition;
• avoid unrelated cleanup, formatting, refactoring, or dependency changes;
• follow the Arcane app-building SOP when it adds or changes a reusable capability.

If the request was diagnosis-only, stop after inspection and report the observed cause and any remaining uncertainty before this step.

Gate: The code change can be explained directly from the manually verified correction.

8. Rebuild

Rebuild, repackage, restart, or invalidate caches only when verification is expressly authorized or required for a selected output, and only to the extent needed for that selected work.

Verify which artifact, version, process, module, or cached resource is actually running afterward. A successful build proves only that the build completed; it does not prove the bug is fixed.

Gate: The test environment is known to be running the corrected output.

9. Retest from a clean state

When clean-state retesting is authorized, return to a clean, representative starting state and repeat the original reproduction exactly.

Then verify in this order:

1. the original reproduction;
2. the focused regression or contract check;
3. the nearest integration, browser, runtime, host, or package path;
4. broader checks proportional to the risk.

A passing check proves only its own boundary. Record each authorized check that ran and every runtime verification that was not authorized or not performed.

Gate: The original observed failure no longer occurs, the verified expectation is met, and the result is attributable to the supported fix.

Compact debugging record

Humans and artificial-intelligence (AI) agents must maintain this record during an investigation:

### ASS-U-ME debugging record

**Reported behavior**
- Conditions/action:
- Observed result:
- Claimed expectation:
- Verified basis for expectation:

**Reproduce**
- Exact reproduction:
- Result:

**Preserve**
- Evidence and failing state saved:

**Inspect**
- Observed facts:
- Verified expectations:
- Questions:
- Possible explanation under test:
- Cardinality and loop multiplier:
- Expensive-operation count/time:
- Invariant / identity-bound per item / batchable classification:
- Request-to-acknowledgement time and foreground call chain:
- Background owner, concurrency/backpressure, progress/heartbeat, and cancellation path:

**Isolate**
- Boundary:
- One variable tested:
- Result:

**Manual correction**
- One change:
- Manual verification result:
- Classification: Proven useful / Disproven / Inconclusive

**Implementation**
- Root cause:
- Code fix:
- Invariant work hoisted/cached and justified repeated work:
- Responsiveness fix and any necessary transaction boundary:
- Rebuild/current artifact observation, if authorized:

**Clean-state retest**
- Original reproduction after fix:
- Focused regression check:
- Broader checks:
- Remaining uncertainty:

Rules for AI agents

An AI agent must:

• select the read-only diagnosis path, authorized fix path, or expressly authorized verification stages before beginning work;
• use the applicable sequence in this document rather than stacking generic hypotheses;
• never present an assumption as a fact;
• verify the expectation before deciding that observed behavior is a defect;
• state the current step in meaningful progress updates;
• perform only one state-changing diagnostic action at a time;
• inspect its result before choosing the next action;
• preserve unrelated user changes;
• stop before implementation when the request is diagnosis-only;
• report the evidence, root cause, fix, and every verification run or not run in the final handoff.

The agent may continue through safe, in-scope steps without pausing for approval after every step. “One step at a time” means one interpretable action at a time, not unnecessary conversational pauses.

Prohibited behavior

Do not:

• begin with “the cause is probably...” and change code to match the guess;
• accept the reported expectation without verifying its basis;
• use the proposed fix as the problem statement;
• make a code change before reproducing and preserving the failure when that verification is expressly authorized and safely possible;
• change multiple independent variables in one experiment;
• erase the original evidence before capturing it;
• treat correlation, timing, or a disappearing symptom as root cause;
• change a test to accept behavior that contradicts the verified requirement;
• suppress public-contract validation, malformed-input rejection, platform safety, credential protection, privacy choices, or error visibility to hide a failure;
• suppress an error, ignore an exit code, add an empty catch, or retry forever;
• claim success from compilation or an unrelated test;
• leave temporary logging, bypasses, credentials, unsafe flags, or diagnostic data behind.

Urgent containment

If the failure is actively causing data loss, credential or secret exposure, protected-data disclosure, destructive behavior, notification storms, or a widespread outage, contain the harm first with the smallest reversible action within the user's authority. Record what was changed, preserve the complete safe diagnostic content, and then return to read-only inspection unless further diagnostic or verification work is expressly authorized.

Containment stops harm. It does not establish the cause or complete the fix.

Completion criteria

A diagnosis is complete when a reviewer can trace a straight line from:

1. the exact observed result;
2. the verified expectation;
3. the preserved failing state;
4. the inspected first incorrect transition or the exact remaining uncertainty.

For an authorized fix, also identify the smallest source correction and report whether reproduction, manual verification, rebuilding, tests, or clean-state retesting were authorized and performed. Unrequested verification is not a completion gate. If the evidentiary chain contains an assumption, label it as an open question rather than presenting it as fact.