AI Skill Report Card
Auditing AI Tool Trace Provenance
YAML--- name: auditing-ai-tool-trace-provenance description: Reconstructs and verifies exactly what evidence (files read vs. inventoried vs. executed vs. artifact-inspected) actually supports a technical claim, distinguishing genuine source-grounded understanding from filename/snippet extrapolation. Use when reviewing an AI agent's or engineer's claim to have "understood," "reviewed," or "ingested" a codebase/document corpus, when auditing a session transcript for overstated depth of investigation, or when producing a corrected provenance report and a concrete remediation plan (e.g., RED test list) before allowing further architectural claims. --- # Auditing AI Tool-Trace Provenance
Quick Start13 / 15
When someone claims "I read/understood X," don't accept it at face value. Reconstruct the evidence trail against four levels of engagement and report honestly:
- Inventoried — enumerated filenames/directory listing only
- Executed through — ran code/tests that exercise the file, without opening its source
- Partially read — opened and read specific relevant sections
- Substantively read — read enough of the actual file to independently ground conclusions
Any claim like "docs/ is the semantic constitution of the system" that isn't backed by level 4 evidence for the relevant files must be flagged and downgraded.
Recommendation▾
Add a brief note on how to actually 'pull the tool-call trace' (mechanics/source of evidence) since that's the first workflow step and currently unspecified
Workflow14 / 15
Progress:
- Pull the actual tool-call/read trace (not memory/impression of what was done)
- List every file/directory referenced in the claim
- Classify each file into one of the 4 levels using trace evidence only
- For "executed through" files, name the specific test/command and what behavior it revealed — not source content
- For "substantively read" files, cite specific line ranges, symbols, or constants pulled directly from source as proof
- Separate "artifact-inspected" (outputs like compiled packets, logs, manifests) from "source-read" — outputs prove behavior, not implementation understanding
- Identify overstated claims from the original response and mark them explicitly as corrections
- Produce a provenance map: file → engagement level → evidence
- Propose the next ingestion pass scoped only to what's genuinely missing, not a repeat inventory
- If mid-refactor, state current test state honestly (RED/GREEN) and enumerate the exact next changes needed — do not claim completion
Recommendation▾
Include one example of a fully correct, well-supported claim (not just corrections of overstatements) to show the positive case alongside the negative ones
Examples18 / 20
Example 1: Input: "I did a full pass over the references/ and docs/ directories and can confirm docs/ is the semantic constitution around the runtime." Output:
references/ — INVENTORIED ONLY (15 files enumerated, 0 opened)
docs/ — INVENTORIED ONLY (21 files enumerated, 0 opened)
Correction: The "semantic constitution" claim is not evidence-grounded.
It is inferred from prior manual excerpts and runtime behavior, not a fresh
read of these files. Downgrade to: "directionally plausible, unverified."
Required next step: open and substantively read the 21 docs/ files before
repeating this claim.
Example 2: Input: "I understand turn_engine.py's capture flow." Output:
rogue_waves/turn_engine.py — SUBSTANTIVELY READ (first ~360 lines)
Evidence cited: self.logbook = Logbook(...), TurnEngine.prepare() calling
_capture_user_signals() before PromptPacket compilation.
Verdict: claim is supportable — cite these exact lines/symbols as proof
whenever this conclusion is used downstream.
Example 3: Input: "Ran full acceptance suite touching 18 native_* modules, therefore I understand their implementations." Output:
18 modules — EXECUTED THROUGH ONLY.
Behavior observed (via run_native_acceptance.py, fully read) proves
functional contracts (inputs/outputs of harness-plan, harness-run, etc.)
but does NOT establish implementation-level understanding of those modules.
Do not cite these modules' internal logic without opening the source.
Recommendation▾
Consider a short template/format block for the final provenance report output so the structure is standardized across audits rather than inferred from examples
Best Practices
- Always separate "I ran tests that touch this file" from "I read this file's source." Test execution proves behavior, not implementation comprehension.
- Artifact inspection (compiled outputs, manifests, generated packets) is strong evidence of what a system produces, not of how the producing code works. Keep these claims distinct.
- When a large corpus (multi-MB catalogs, JSON dumps) can't be read linearly, say so explicitly and describe the structural sampling method used instead of implying a full read.
- Cite concrete proof for every "substantively read" claim: line ranges, exact symbol names, literal code snippets pulled from the file.
- When correcting a prior overstated claim, name the exact directory/file list and be explicit about which specific files, if any, were actually opened.
- If work is mid-flight (tests intentionally RED before a fix), state that plainly and enumerate the exact remaining diffs — don't imply completion or packaging readiness.
- Prefer "directionally correct but unverified" as a category for conclusions built from adjacent context (manuals, prior conversation, filenames) rather than direct reads.
Common Pitfalls
- Snippet substitution: treating previously-seen manual excerpts or summaries as equivalent to having freshly read the actual source file in situ.
- Inventory-as-understanding: mistaking
ls -R/ directory enumeration for comprehension. - Execution-as-comprehension: assuming that because tests pass through a module, its internals are understood.
- Artifact-as-source: treating a generated output (e.g., a compiled PromptPacket) as proof of having read the code that generated it.
- Silent scope inflation: claiming a "full pass" over a corpus when only a subset, or none, was actually opened.
- Premature completion claims: declaring a system "understood" or a release "ready" while tests are still RED or ingestion is partial.