/provenance-methodology

name: provenance-methodology
description: Cross-cutting provenance discipline. Citation format, confidence levels, source hierarchy, session capture. Loaded by every analysis agent.

Provenance Methodology

Every behavioral claim you write MUST have a citation. No exceptions.

The Citation Rule

A "behavioral claim" is any assertion about what the target system does, how it responds, what data it accepts or produces, what errors it raises, what limits it enforces, or how it transitions between states.

**Cite as you go.** Do NOT batch citations at the end of your analysis. Every time you write a behavioral claim, the very next thing you write is the citation.

Citation Format

Inline HTML comment, immediately after the claim:

- Sessions expire after 30 minutes of inactivity
  <!-- cite: source=official-docs, ref=https://docs.example.com/sessions#timeout, confidence=confirmed, agent=doc-researcher, corroborated_by=runtime-observation -->

Required Fields

| Field | Type | Description | |-------|------|-------------| | `source` | enum | The type of source (see Source Types below) | | `ref` | string | Specific location: URL, `workspace/` file path with optional `:line`, or session timestamp | | `confidence` | enum | `confirmed`, `inferred`, or `assumed` (see Confidence Levels below) | | `agent` | string | Your agent name |

Optional Fields

| Field | Type | Description | |-------|------|-------------| | `corroborated_by` | comma-separated list | Other source types that independently confirm this claim | | `session` | string | Agent ID for session log in `workspace/provenance/sessions/` |

Placement Rules

• The `<!-- cite: -->` comment MUST appear on the line immediately following the claim it supports, or on the same line after the claim text.
• If a single claim is supported by multiple independent sources, use a single citation with `corroborated_by` listing the additional sources.
• If a paragraph contains multiple claims, each claim gets its own citation. Break compound sentences into separate cited items.
• Block-level claims (tables, code blocks, decision trees) place the citation comment immediately after the closing block.

Source Types (Strongest to Weakest)

| Rank | Source Type | When to Use | Origin | |------|-----------|-------------|-------| | 1 | `official-docs` | Published documentation, README, man pages, API references, changelogs | PUBLIC | | 2 | `public-api` | Observed behavior of public API endpoints, CLI commands | PUBLIC | | 3 | `sdk-analysis` | Published SDK, client library, or plugin source code | PUBLIC | | 4 | `community-knowledge` | Stack Overflow, blog posts, conference talks, third-party tutorials | PUBLIC | | 5 | `runtime-observation` | Behavior observed by running the product in a container | RAW | | 6 | `source-code` | Proprietary source code, bundles, minified JS | RAW | | 7 | `binary-analysis` | Disassembly, decompilation, binary instrumentation | RAW | | 8 | `inferred` | Reasoning, convention, analogy. No direct observation. | N/A |

Agent Source Type Guide

| Agent | Primary Source Type | |-------|-------------------| | `doc-researcher` | `official-docs` or `community-knowledge` | | `sdk-analyzer`, `integration-test-miner` | `sdk-analysis` | | `bundle-splitter`, `chunk-analyzer`, `function-analyzer`, `targeted-extractor` | `source-code` | | `cli-explorer`, `web-ui-explorer`, `behavior-observer`, `ux-documenter` | `runtime-observation` | | `binary-surveyor`, `binary-deep-analyzer` | `binary-analysis` | | Layer 2 synthesis agents | Cite upstream agent output files | | Layer 3 documentation agents | Cite all supporting evidence from any source |

Confidence Levels

`confirmed`

Two or more independent sources agree, OR a single runtime observation with reproducible steps.

**Use when:**

• Official docs state X AND source code confirms X
• Runtime observation shows X AND SDK client handles X
• Two independent community sources describe X consistently
• A single reproducible runtime observation (documented input, steps, output)

`inferred`

One authoritative source, no contradictions.

**Use when:**

• Official docs state X but no second source confirms it
• Source code clearly implements X but no docs mention it
• A single well-regarded community source describes X, consistent with known behaviors

`assumed`

Convention, pattern matching, or reasoning. No direct source.

**Use when:**

• Following a common convention (e.g., "REST API probably returns JSON") but no source confirms
• A pattern in one module is assumed to apply in another
• Evidence is partial and the claim is the most plausible interpretation
• Filling a spec gap where behavior must exist for the system to function

How to Determine Confidence

digraph confidence_determination {
    rankdir=TB;

    "Determine confidence level" [shape=doublecircle];
    "How many independent sources?" [shape=diamond];
    "Is the source authoritative?" [shape=diamond];
    "Any contradicting evidence?" [shape=diamond];
    "Use confirmed" [shape=box];
    "Use inferred" [shape=box];
    "Use assumed" [shape=box];
    "STOP: Record the contradiction" [shape=octagon, style=filled, fillcolor=red, fontcolor=white];

    "Determine confidence level" -> "How many independent sources?";
    "How many independent sources?" -> "Any contradicting evidence?" [label="2 or more"];
    "How many independent sources?" -> "Is the source authoritative?" [label="1"];
    "How many independent sources?" -> "Use assumed" [label="0"];
    "Is the source authoritative?" -> "Use inferred" [label="yes"];
    "Is the source authoritative?" -> "Use assumed" [label="no"];
    "Any contradicting evidence?" -> "STOP: Record the contradiction" [label="yes"];
    "Any contradicting evidence?" -> "Use confirmed" [label="no"];
}

**Authoritative sources:** official docs, source code, runtime observation, specific community content. **Not authoritative:** your own