Investigation Standard¶

Parent contract: Bluefly Engineering Execution Contract Version: 1.0 Applies to: All roles, all platforms. Governs investigation method. Reporting of findings: Evidence Reporting Standard. Sources and termination: Engineering Authority Exhaustion (NOT_FOUND).

1. The Law¶

A failed execution is evidence that the execution failed. It is not evidence explaining why it failed.

Describe what happened. Distinguish it from why it happened. Treat the cause as unknown until demonstrated by evidence. "Command failed" never becomes "authentication broken" without proving every intermediate step.

2. Observation¶

An observation is the exact command, exit code, stdout, and stderr — captured verbatim, with timestamp and environment. No interpretation in the same statement. An uncaptured detail (a lost exit code) is reported as missing, never reconstructed from memory.

3. Verification¶

A claim is verified only when tested against a primary source (runtime probe, file content, documented behavior exercised). Seeing a related symptom is not verifying the claim. See the capability-claim ladder (Evidence Reporting Standard §2.1).

4. Reproduction¶

One occurrence is an observation, not a behavior. Before generalizing ("X always fails", "X is broken"), reproduce it — or report it as a single observation. An unreproduced failure supports no conclusion beyond itself. Reproduction that would mutate state requires the same authorization as any mutation.

5. Capability vs Execution¶

These are different questions, always reported independently:

Capability
  Question:  Does the tool support the operation?
  Evidence:  <help output / documentation / schema>
  Result:    YES | NO | UNKNOWN

Execution
  Question:  Did this execution succeed?
  Observed:  <exact command>
  Exit:      <code>
  stdout:    <exact output>
  stderr:    <exact output>
  Result:    SUCCEEDED | FAILED
  Root Cause: <demonstrated cause | "Evidence insufficient to determine.">

A supported capability that failed once does not imply the capability is absent. Evidence that a capability is absent should come from the tool's authoritative surface (such as its documented interface, schema, or help output), not from a failed execution alone.

6. Unknowns Ledger¶

Every investigation ends with an explicit unknowns ledger. Each item is either ELIMINATED (with the evidence that eliminated it) or UNRESOLVED — never silently dropped:

UNKNOWNS
□ authentication   □ authorization   □ configuration   □ network
□ API              □ runtime         □ permissions     □ operator policy
□ environmental    □ other

The ledger exists to prevent stopping at the first plausible explanation. A plausible explanation with unresolved alternatives is a hypothesis, not a finding.

7. Root Cause¶

Root cause is declared only when an evidence chain links cause to effect and the alternatives in the unknowns ledger are eliminated. Until then, the only correct statement is: "Root cause has NOT been determined." Architectural root-cause claims remain INFERRED until validated (Engineering Authority Exhaustion (NOT_FOUND)).

8. Investigation Outputs¶

An investigation never changes architecture. An investigation produces evidence. Evidence may update:

Capability Authority
Canonical Implementation
Portable Engineering Assets
Pack
Project
Deployment

The investigation itself owns none of these. It only provides evidence that allows the authoritative owner to change them. Investigation sits before governance in the chain (Observation → Verification → Reproduction → Evidence → Capability Authority → Canonical Implementation → Portable Engineering Assets → Pack → City → Deployment); it does not become governance.

9. Closure¶

An investigation closes in exactly one state:

ROOT-CAUSED — cause demonstrated, unknowns eliminated.
REPRODUCED-UNEXPLAINED — behavior reproducible; cause still unknown (ledger attached).
EVIDENCE-INSUFFICIENT — stated plainly, with what was and was not established.
BLOCKED_EXTERNAL — every available engineering authority exhausted (per the exhaustion standard).

Closing an investigation is distinct from closing the task it serves; task terminal states are defined in status-legend.md.

This standard governs how investigations are conducted. It does not govern what is reported (Evidence Reporting Standard) or when investigation may stop (Engineering Authority Exhaustion).