White box trace

White-Box Trace (REAL + VIRTUAL)

MISSION: prove correctness — of code that exists (REAL) or of an artifact describing code that does not yet exist (VIRTUAL) — by falsifying every conclusion before declaring it. Investigation only. NO source modification. Skipping any MANDATORY gate ⇒ INVALID DELIVERABLE → REDO.

Layering: skill = trace-specific layer over CLAUDE.md. Cite §N — DO NOT duplicate. CLAUDE.md provides Tier (§3), Checkpoint (§4), Evidence ladder (§4.5/§6), Adversarial Toolkit (§7), Output Contract (§9), Pre-Send Checklist (§11), Repro Kernel (§12), Reflexion (§13), P0 #1/#4/#7/#8/#10/#16. Read CLAUDE.md FIRST.

---

0. Hard rules — VIOLATING ANY ⇒ INVALID DELIVERABLE → REDO

1. No source modification. NEVER Edit or Write production code. Output: trace JSONL + report + (FAIL only) repro_snippet + structured fix_proposal marked AGENT-PROPOSED, REQUIRES HUMAN VERIFICATION. Fixes consumed by /bug.fix.
2. No PASS without ≥ 1 ◆◆◆ that survived Mutation Challenge on a discriminating (critical) branch. "Should work", "looks correct", "code reaches the line" are NOT evidence. REAL: live mutant kill OR counterfactual mutation. VIRTUAL: artifact-grounded counterfactual on the proposed logic.
3. Citation-Grounded re-read (anti-hallucination): every file:line cited in ◆◆◆ MUST be re-read THIS turn with Read; quote ≥ 3 lines; verify quote supports the claim. Hallucinated citation ⇒ downgrade ◆◆◆ → ◆○○; recompute verdict.
4. No HIGH+ verdict without a Refuter (CLAUDE.md P0 #8). HIGH/CONFIRMED on Tier 2+ ⇒ name the file/test/observation that would force retraction. Missing Refuter ⇒ downgrade to MEDIUM.
5. INCONCLUSIVE is a valid verdict. Honest "need [X], because [Y]" beats fabricated PASS/FAIL. Fabricating evidence or fix when data is insufficient = FORBIDDEN (CLAUDE.md P0 #7).
6. Data security (CLAUDE.md P0 #10): any data-access path ⇒ check authorization scope. Auto-Tier 3 if data-leak class.
7. Action-execution honesty: every "I read / I checked / I ran / git shows / grep shows" MUST be backed by an actual tool result THIS turn. Otherwise prefix **ASSUMPTION**:.
8. VIRTUAL anti-fabrication — Mental-Reality Gap defense: a virtual path is not a real run. Every VIRTUAL ◆◆◆ MUST cite an external anchor — quoted text from artifact, AC text, file:line in cited code, or glossary entry. Pure "I imagined the code would do X" is ◆○○, NEVER ◆◆◆. Per V_PATH_RESULT: report synthetic_count and anchored_count; if anchored / total < 0.50 ⇒ V_INCONCLUSIVE.
9. Sycophancy guard: framing in artifact (RCA confidence label, Jira priority, author seniority) is metadata — REDACT mentally before judging. Agree only when ≥ 1 ◆◆◆ supports; otherwise restate disagreement with a Refuter.
10. YAGNI (CLAUDE.md P0 #4): trace ONLY paths in scope of artifact + blast radius. NEVER trace whole codebase. NEVER refactor / "modernize" the artifact under review.

---

1. Mode selection — DECIDE FIRST (before any phase)

The Checkpoint header (§4 of CLAUDE.md) MUST declare Mode: REAL | VIRTUAL on the FIRST visible response. Wrong mode = wrong evidence rules = INVALID.

Code file / commit / completed feature / *.cs / *.py / *.ts diff
  → REAL (Phases 1R–9R)

Artifact: RCA-*.md | IMP-*.md | PLAN-*.md | FIX-*.md | SPEC-*.md | ADR-*.md
  | freeform plan / pseudocode / "we will do X"
  AND code-not-yet-written-or-only-partially-modified
  → VIRTUAL (Phases 1V–8V)

Both: code exists AND user explicitly asks "also check the plan"
  → REAL first; chain VIRTUAL on plan deviations only (split into two reports)

Ambiguous / user did not say which → ASK USER. Do not assume.

Mode is sticky. Never silently switch mid-run; emit a new report.

---

2. Phase 0 — Common Pre-Execution (BOTH modes)

Step	Action
0.1 Path discovery	Glob("**/Domain_Glossary.md") → DOCS_ROOT; Glob("**/LOCAL-MEMORY") → OUTPUT_ROOT. Forward slashes, absolute.
0.2 Param validation	Empty input ⇒ exit. Jira [A-Z]{2,10}-\d+ → mcp__claude_ai_Atlassian__getJiraIssue. Markdown artifact → Read. Folder → Glob.
0.3 Capability probe	which {YOUR_MUTATION_TEST_TOOL} (mutation_available); import hypothesis or {YOUR_TEST_RUNNER} --filter Property (pbt_available); Glob("**/.codegraph/*.db") (ckg_available); detect runner. Cache once per session.
0.4 Requirements pre-flight	Load requirements-analysis (when present). Classify Task / Bug / Both. Normalize each AC to EARS: "When <trigger>, the <system> shall <action>". Produce GWT per AC. Assign canonical req_id. Open Questions with ⚠️ ASSUMPTION per gap. open_questions.critical > 0 ⇒ ASK USER before Phase 1.
0.4.5 Architecture Pre-Read (MANDATORY when ANY of: scope crosses ≥ 3 architectural layers (DB → ORM → Domain → Core/Services → Web/API → UI) · touches Core/, domain layer, {YOUR_SERVICE_LAYER}, {YOUR_DATA_ACCESS_LAYER} · security boundary · data-integrity class )	Read context/01_Solution_Overview/Project_Overview.md AND context/03_Projects/{ProjectName}.md when applicable. Record: layer-boundary the data crosses · governing patterns (F/B/D-XXX from Code_Patterns_Index.md) · invariants the boundary enforces. Skipping ⇒ INVALID DELIVERABLE → REDO — without architecture context every PATH_PASS confirms only local correctness while missing inter-layer contract violations (FM-6).
0.5 Reflexion memo load	OUTPUT_ROOT/CURRENT_TASK/TRACE-LESSONS-{task-slug}.md exists ⇒ inject "Prior lessons to avoid: …" into Phase-3 prompts.
0.6 Trace file (REAL)	OUTPUT_ROOT/CURRENT_TASK/TRACE-{task-slug}-{YYYYMMDD}-{HHmm}.jsonl; existing ⇒ parse SCHEMA + HEADER + index-prefixed lines, recompute pass_file_hash, queue DECAY_QUEUED and INTERRUPTED (§8.3).
0.7 Report file (VIRTUAL)	OUTPUT_ROOT/CURRENT_TASK/V-TRACE-REPORT-{artifact-slug}-{YYYYMMDD}-{HHmm}.md; optional sidecar V-TRACE-{artifact-slug}-{YYYYMMDD}-{HHmm}.jsonl.
0.8 Output Checkpoint	Per CLAUDE.md §4. MUST include: Mode: REAL|VIRTUAL, Tooling probe: mutation=… pbt=… ckg=…, Path budget: tier-aware, Lessons memo: loaded:Y/N entries:N, Architecture Context: <layer-boundary; governing F/B/D-XXX; invariants> [when 0.4.5 fires; otherwise N/A], Critical Insight, Killer Hypothesis (REAL = most-likely-broken HAPPY; VIRTUAL = most-likely-falsifiable claim), Refuter, Confidence. Confidence < MEDIUM ⇒ ASK USER before Phase 1.

STOP rules: max 30 paths/run (--max-paths overrides); per-path adaptive budget = 4_000 × (1 + cyclomatic_complexity / 5) tokens; 3× consumed ⇒ PATH_DEFERRED{reason: "budget exhausted"}. Tier-aware default budget: T0=8, T1=15, T2=25, T3=40 paths.

---

3. REAL mode — Phases 1R–9R

3.1 Phase 1R · CFG Construction (MODE=NEW)

• Identify target files/methods (load codebase-search-protocol; if ckg_available, switch to MATCH (m:METHOD)-[:CALLS*1..3]-(n) query).
• Build CFG: if/switch/try-catch/loops/early return/throw. Apply MPC — minimum paths covering every statement (C0) and every branch T/F (C1). Path cap = min(--max-paths, cyclomatic × 3). ≥ 5 branches ⇒ prioritize critical business branches (validation, authorization, permissions, exceptions). Loop policy: 0/1/N iterations.
• Categorize HAPPY / NEGATIVE / EDGE; adversarial stance on NEGATIVE — actively seek failure modes.
• Write CFG_SUMMARY + one PATH record per path: id (P001…), req_id MANDATORY, category, description, entry, branches, status=PENDING, shared_prefix_hash, killer (boolean).
• Killer-Path-First election: among HAPPY, mark exactly one killer=true — highest-cyclomatic node, newest code (≤ 7 d via git log), layer-boundary crossing, recently-fixed area (per memo / git blame). Killer is traversed FIRST.

3.2 Phase 2R · Resume

pending = all_paths − completed − INTERRUPTED − DEFERRED − DECAY_QUEUED. Write RESUME_START (with lessons_memo_hash).

3.3 Phase 3R · Per-Path Protocol — order: Killer HAPPY → other HAPPY → NEGATIVE → EDGE

1. Stale context check — re-read entry + key branch lines; mismatch ⇒ PATH_DEFERRED, queue.
2. Write PATH_START.
3. Read entry / branches / exit (codebase-search-protocol or CKG).
4. Set context (input data, expected behavior from req_id).
5. Trace — per step write PATH_EVIDENCE (file, line, quoted_code, weight ◆◆◆ / ◆◆○ / ◆○○, supports). External lib / API / CVE ⇒ web-search-protocol, ◆◆○ + cite URL. Inter-path coverage propagation — shared_prefix_hash matches earlier PASS path ⇒ reuse prefix evidence as ◆◆○ (one-step downgrade); collect fresh ◆◆◆ on divergent suffix only.
6. Verify postcondition (return value / side effect / exception).
7. Mutation Challenge — counterfactual (MANDATORY): per ◆◆◆ apply ≥ 3 mutations (condition flip ≤ → <, off-by-one i<n → i<=n, wrong enum, swap operand, wrong source). ALL mutants would still produce PASS ⇒ downgrade ◆◆◆ → ◆◆○ (non-discriminating). ≥ 1 mutant clearly fails ⇒ keep ◆◆◆. Record mutation_tested=true, mutation_outcome ∈ {killed, survived}. Absent fields = INVALID PATH_RESULT — REDO. PATH_PASS REQUIRES ≥ 1 ◆◆◆ that survived.
8. Live Mutation (mutation_available && --mutation∈{live,hybrid}) — {YOUR_MUTATION_TEST_TOOL} --since=HEAD~1 [scoped to changed files only — NEVER prod]. Killed mutants ⇒ ◆◆◆ empirical. Survivors ⇒ coverage_gap; PATH_PASS REQUIRES mutation_kill_rate ≥ 0.75 on changed lines.
9. PBT (pbt_available && --pbt=on && path.has_invariant) — property-based test on path invariants × 100. All pass ⇒ ◆◆◆+ (strongest). Any fail ⇒ minimal counterexample = repro_snippet; STATUS=FAIL.
10. Agentic Concolic (≥ 3 chained boolean conditions) — natural-language constraint summarization; ask "exists input violating this path's expectation while satisfying all conditions?". Constructive counterexample ⇒ STATUS=FAIL with input as repro_snippet.
11. Discriminating-evidence rule: ≥ 1 PASS ◆◆◆ MUST be on this path's critical branch (the branch distinguishing this path from a CFG sibling). All ◆◆◆ in shared prefix only ⇒ STATUS=FAIL, failure_reason="no discriminating evidence".
12. Evidence Re-Read Gate (CoVe, MANDATORY) — per ◆◆◆ → Read exact file:line, quote ≥ 3 lines, verify quote supports claim. Use targeted phrasing only: "Does the quoted code support this step's claim?" — NEVER "find all your mistakes" / unbounded critique. Failure ⇒ downgrade or STATUS=FAIL. Absent gate = INVALID PATH_RESULT — REDO.
13. Output to chat: #### Path P00X Verdict: PASS | FAIL — [one phrase: why].
14. Write PATH_RESULT (status, verdict, evidence_count, strong_evidence, mutation_tested, mutation_outcome, mutation_kill_rate, pbt_applied, pbt_passed, pass_file_hash, failure_location, failure_reason, repro_snippet 5–15 lines, fix_proposal structured JSON, reviewer_disagreement).
15. Write COVERAGE.

FAIL-FAST: first HAPPY=FAIL ⇒ FOOTER{status=FAIL_FAST}, skip remaining HAPPY/NEGATIVE/EDGE, jump to Phase 6R + 7R + 9R.

Proof-of-Negative: HAPPY=FAIL ∧ (NEGATIVE=PASS ∨ EDGE=PASS) ⇒ write PROOF_OF_NEGATIVE — regression-class signature.

3.4 Phase 4R · Coverage

Statement C0 ≥ 80%; Branch C1 ≥ 70%; Mutation kill rate ≥ 75% (live); HAPPY 100% / NEGATIVE 80% / EDGE 60%. Discriminating-coverage gate: every covered req_id MUST have ≥ 1 PASS path with ◆◆◆ that survived mutation AND on its critical branch — otherwise the req moves to non_discriminating_requirements and verdict ≥ ISSUES.

3.5 Phase 5R · Blast Radius

Trigger: public/shared method, domain entity/DB schema, cyclomatic > 3. Forward-slice; add BLAST_RADIUS paths to plan; same per-path protocol.

3.6 Phase 6R · Failure Diagnosis (FAIL paths only)

Error Propagation Table (MANDATORY) — Hop | Layer | File:Line | Component | Expected | Actual | Valid? | Note — from failure_location (Hop 0) to Corruption Point (first ✅→❌ flip) to Root Cause. Depth: 2–3 single-method, 4–6 cross-layer, max 8. Tandem-FL (4+ hops or value-propagation): SBFL Ochiai top-N → dynamic backward slice from (failure_location, failing_var). ROOT_CAUSE_BOX references the table by Hop. repro_snippet (5–15 lines, runnable) + structured fix_proposal MANDATORY.

3.7 Phase 7R · Reviewer Agent Pass

Trigger: --reviewer-agent=auto ∧ ≥ 1 FAIL path. Spawn Agent (subagent_type: Explore) with isolated context (no Debugger contamination): "Re-rank the top-N suspicious lines from Tandem-FL. Are any clear red herrings? Is the true root cause possibly outside this set?" Disagreement ⇒ reviewer_disagreement field; both rankings in report §5; verdict = consensus or ISSUES_REVIEW_CONFLICT if conflict + similar confidence.

3.8 Phase 8R · Final Verification (CHAT ONLY — never saved)

1. Contradiction Detector (CLAUDE.md §11.9 — seven types) + new types: mutation gap (live mode but kill_rate < 0.75), discriminating gap (any req in non_discriminating_requirements), reviewer conflict.
2. CoVe micro-check — Draft → Verify ("does every PASS have ≥ 1 ◆◆◆ mutation_tested=true on critical branch?" — filter PATH_RESULT + PATH_EVIDENCE) → Synthesize. No ⇒ downgrade.
3. Disconfirmation-First on PASS — MUST output in chat: "Disconfirmation check: <single most likely reason this PASS is wrong>. Result: <holds | falsified>." Falsified ⇒ downgrade. Absent line = REDO.
4. Self-Consistency vote (borderline only) — one PASS barely survived mutation OR coverage within 5% of threshold ⇒ re-traverse that path 3× with fresh seeds; majority verdict; record SELF_CONSISTENCY_VOTE.
5. Sycophancy guard — re-read artifact framing; flag any "HIGH confidence" / "trivial fix" / "should already work" not backed by evidence.
6. Pre-Send Checklist (CLAUDE.md §11) — all 12 items.
7. Write FOOTER. On FAIL retry, write Reflexion memo → TRACE-LESSONS-{task-slug}.md: "What was hypothesized PASS but FAILed; branch most underestimated; mutation that killed strongest evidence; tip for next attempt".

3.9 Phase 9R · Report

TRACE-REPORT-{task-slug}-{YYYYMMDD}-{HHmm}.md per report-template.md §B (Sections 0–11). Phase 8R outputs NEVER in saved files — chat only.

---

4. VIRTUAL mode — Phases 1V–8V

VIRTUAL ≠ REAL. No code is run. The artifact is the unit of analysis. Evidence = artifact-grounded (quoted text + cited file:line if any) — NOT "I imagined the code did X" (= ◆○○ or **ASSUMPTION**:). Mental-Reality Gap is the central anti-pattern (§0 rule 8).

4.1 Phase 1V · Artifact Ingestion

Identify type: RCA / IMP / PLAN / FIX / SPEC / ADR / freeform. Read the artifact in full. Extract:

• RCA: proposed Root Cause + Invariant + Repro Spec + Primary Fix Box + Hypotheses table.
• IMP/Plan: target files, target methods, declared logic, ACs, invariants, security claims.
• Freeform: convert to EARS+GWT (Phase 0.4).

fingerprint = sha256(artifact_text || referenced_file:line_content_currently_on_disk).

4.2 Phase 2V · Virtual CFG Construction (Planner-Simulator)

• Build a CFG of the intended logic from the artifact text — not from existing code (which may not exist). Branch points come from the artifact's stated conditions, validations, error handling, loops.
• Artifact references existing files (file:line) ⇒ Read them — they are real anchors. Mark each CFG node anchored (real code) or synthetic (only described).
• Apply MPC; categorize HAPPY / NEGATIVE / EDGE; assign req_id per AC.
• Emit V_CFG_SUMMARY, V_PATH records (schema mirrors REAL PATH plus kind="virtual", anchored:[file:line list], synthetic_branches:[…]).

4.3 Phase 3V · Virtual Path Traversal — order: Killer-AC-First → other ACs → negative ACs → edge ACs

1. Write V_PATH_START.
2. State the precondition + AC literal text the path is supposed to satisfy.
3. Walk the artifact's stated logic step-by-step; per step write V_PATH_EVIDENCE:
   • Quote the artifact text (source: artifact, line_in_artifact: N) → ◆◆○ baseline.
   • Step references existing code (file:line) ⇒ Read, quote ≥ 3 lines, verify support → ◆◆◆ (anchored).
   • Pure inference ("the developer probably meant X") → ◆○○; NEVER PASS-grade.
4. AC satisfaction check — does the walked logic necessarily produce the AC's expected output under the stated precondition? Yes / No / Unknown.
5. Virtual Mutation Challenge (artifact-grounded) — apply ≥ 3 mutations to the artifact's stated logic: flip a condition the artifact describes, drop a validation step it lists, swap order of stated calls, weaken an invariant. Mutated logic still satisfies AC ⇒ artifact is under-specified (non-discriminating); downgrade ◆◆◆ → ◆◆○ and add an Open Question. Mutation breaks AC ⇒ keep ◆◆◆.
6. Cross-artifact drift check — parent exists (RCA → IMP, IMP → SPEC) ⇒ every claim MUST be consistent with parent. Drift ⇒ V_DRIFT record; verdict ≥ V_ISSUES.
7. LTL-style consistency — convert path's stated steps to ordered logical predicates: step₁ ⇒ step₂ ⇒ … ⇒ AC. Inconsistency / ordering bug ⇒ STATUS=V_FAIL with the contradiction printed.
8. Mental-Reality Gap audit (MANDATORY) — name explicitly which steps are anchored vs synthetic. > 50% synthetic ◆◆◆ in this path ⇒ downgrade to V_INCONCLUSIVE, reason "Verification Gap — too much imagined trace, not enough reality".
9. Citation-Grounded re-read (§0 rule 3) — every cited file:line re-read THIS turn.
10. Output to chat: #### V-Path V00X Verdict: V_PASS | V_FAIL | V_INCONCLUSIVE — [phrase].
11. Write V_PATH_RESULT (+ for V_FAIL: repro_snippet_pseudocode 5–15-line input violating AC under artifact logic; fix_proposal_to_artifact — what to add/edit IN THE ARTIFACT, NOT in code).

4.4 Phase 4V · POPPER Falsification-First

For each surviving V_PASS hypothesis (proposed root cause / proposed plan path), name the single most discriminating mental experiment that would falsify it. Run it (mentally + grounded in artifact). Survives ⇒ keep V_PASS. Falls ⇒ V_FAIL. Cannot design ⇒ V_INCONCLUSIVE.

4.5 Phase 5V · Cross-Artifact Consistency

4-column table: Claim | Source artifact (RCA/IMP/SPEC) | Conflicts with | Severity. Drift on Root Cause / Invariant / AC / file:line target ⇒ V_ISSUES. Output feeds /bug.fix or /howto.implement so they don't act on stale plan.

4.6 Phase 6V · Virtual Coverage + AC Map

Coverage	Min
AC coverage	100% — each AC has ≥ 1 V_PASS path with discriminating ◆◆◆
Anchored evidence ratio	≥ 50% of V_PASS ◆◆◆ are anchored (file:line)
Synthetic-only paths	≤ 30% — else V_INCONCLUSIVE
Auth scope	100% on every data-touch path

4.7 Phase 7V · Final Verification (CHAT ONLY)

Same gates as REAL Phase 8R (Contradiction Detector, CoVe, Disconfirmation-First on V_PASS, Sycophancy guard, Pre-Send Checklist) plus Mental-Reality Gap final audit (anchored-vs-synthetic ratio across whole report).

4.8 Phase 8V · Report

V-TRACE-REPORT-{artifact-slug}-{YYYYMMDD}-{HHmm}.md per report-template.md §C (Sections V0–V11). Output IS the deliverable — never modify the source artifact.

---

5. Shared Evidence Framework

Weight	Symbol	REAL rule	VIRTUAL rule
STRONGEST	◆◆◆+	Direct read file:line + quoted_code + survived live mutation + PBT properties hold	Direct quote from artifact + verified file:line anchor + survived virtual mutation + LTL consistent
STRONG	◆◆◆	Direct read file:line + quoted_code + survived counterfactual mutation on critical branch	Direct quote from artifact + verified file:line anchor + survived virtual mutation
MODERATE	◆◆○	Inferred from related code; or ◆◆◆ where mutation survived but did not kill	Quote from artifact only (no code anchor); or step where artifact + glossary agree
WEAK	◆○○	Assumption / analogy; NEVER allowed for PATH_PASS	Pure inference / "the developer probably meant"; NEVER allowed for V_PATH_PASS

No ◆◆◆ ⇒ no PASS. No ◆◆◆ that survived Mutation Challenge on critical branch ⇒ no PASS. VIRTUAL: anchored ◆◆◆ ratio < 0.50 ⇒ V_INCONCLUSIVE.

---

6. Anti-Hallucination Gate Stack — run all in chat, never in saved files

Gate	When	Defends against
Citation-Grounded re-read	Per ◆◆◆, before any PASS	Fabricated file:line, out-of-range citation
Mutation Counterfactual	Per ◆◆◆, before PATH_PASS / V_PATH_PASS	Non-discriminating evidence; FL fragility
CoVe micro-check	Before final verdict	Hallucinated trace, fact drift
Disconfirmation-First on PASS	Before final PASS — chat output MANDATORY	Confirmation bias, overconfidence
Sycophancy guard	Before final verdict	Adversarial framing, false-PASS
Self-Consistency vote	Borderline only	Single-trace luck
Mental-Reality Gap audit (VIRTUAL)	Before V_PASS	Imagined-trace self-affirmation loop

---

7. Verdict Matrix

Mode	Verdicts (best → worst)
REAL	PASS · PASS_WITH_NOTES · ISSUES · ISSUES_REVIEW_CONFLICT · FAIL · FAIL_FAST
VIRTUAL	V_PASS · V_PASS_WITH_NOTES · V_ISSUES · V_INCONCLUSIVE · V_FAIL

Completion gates (PASS / V_PASS):

• All planned paths resolved.
• HAPPY / NEGATIVE / EDGE (REAL) or AC (VIRTUAL) covered.
• unverified_claims == 0; uncovered_requirements == 0; non_discriminating_requirements == 0.
• (REAL live) mutation_kill_rate ≥ 0.75.
• (VIRTUAL) anchored_evidence_ratio ≥ 0.50.
• All §6 gates passed.

---

8. Output paths + JSONL format

8.1 Paths (forward slashes, absolute)

• REAL trace: OUTPUT_ROOT/CURRENT_TASK/TRACE-{task-slug}-{YYYYMMDD}-{HHmm}.jsonl
• REAL report: OUTPUT_ROOT/CURRENT_TASK/TRACE-REPORT-{task-slug}-{YYYYMMDD}-{HHmm}.md
• VIRTUAL report: OUTPUT_ROOT/CURRENT_TASK/V-TRACE-REPORT-{artifact-slug}-{YYYYMMDD}-{HHmm}.md
• VIRTUAL JSONL (optional): …/V-TRACE-{artifact-slug}-{YYYYMMDD}-{HHmm}.jsonl
• Lessons memo (BOTH): …/TRACE-LESSONS-{task-slug}.md
• BUG-* / STORY-* subfolders override CURRENT_TASK when artifact lives there.
• YAML frontmatter MANDATORY per CLAUDE.md §9: artifact_type: TRACE | V-TRACE | LESSON, producer: claude-code, state: draft|verified|superseded, inputs_consumed[], fingerprint, tier, targets_failure_modes, verification block.

8.2 JSONL — Index-Prefix Append (only allowed format)

0001:{"type":"SCHEMA","version":"2.1","mode":"REAL|VIRTUAL","resume_format":"index-prefix","mutation_mode":"…","pbt_mode":"…"}
0002:{"type":"HEADER","task_ref":"…","task_fingerprint":"sha256:…","target_files":[…],"created":"…","session_id":"…"}
NNNN:{"type":"PATH_START|PATH_EVIDENCE|PATH_RESULT|COVERAGE|PROOF_OF_NEGATIVE|SELF_CONSISTENCY_VOTE|RESUME_START|FOOTER", …}

Append protocol: next_seq = max(existing_seq) + 1; line begins with NNNN:. Resume parse: split lines → parse seq:json → sort by seq → filter PATH_RESULT → {path_id, status, pass_file_hash}. Variant-C marker (legacy) is DEPRECATED — FORBIDDEN in new traces.

8.3 Resume table

Path status	Action
PASS, hash unchanged	Skip
PASS, whitespace-only diff	Skip + stale-warn
PASS, code diff	DECAY_QUEUED → re-traverse
FAIL, target unchanged	Skip
FAIL, target changed	Re-check
INTERRUPTED / DEFERRED / DECAY_QUEUED / PENDING	Traverse

---

9. Tool / skill usage

Situation	Action
Searches / file location	codebase-search-protocol (CLASSIFY → LOCATE → FILTER → SCAN).
8-method theory / formulas / scientific anchors	reference.md — never inline.
Deep RCA on FAIL	Hand off to root-cause-analysis (/bug.why); pass trace + Error Propagation Table.
Implementation after V_PASS	Hand off to /howto.implement; pass V-TRACE report.
Fix application after FAIL	Hand off to /bug.fix; pass trace + fix_proposal JSON + repro_snippet.
Multi-layer (≥ 3 layers)	Spawn Agent (subagent_type: Explore) per layer; main agent writes (CLAUDE.md §14).
Jira / Confluence	Atlassian MCP (mcp__claude_ai_Atlassian__*).
External library / CVE	WebSearch then WebFetch known URL — ◆◆○ MODERATE; cite source URL.
Mermaid CFG / Error Propagation	mermaid-diagrams.

---

10. Anti-Patterns — FORBIDDEN

❌	✅
Modify source code	Read only — output trace + report
PASS without ◆◆◆ on critical branch	≥ 1 ◆◆◆ on the discriminating branch
◆◆◆ without Mutation Challenge	Counterfactual ≥ 3 mutations + (when available) live
"Should work" / "looks correct" / "code reaches here"	Concrete code quote + mutation outcome
Skip NEGATIVE or EDGE (REAL) / skip an AC (VIRTUAL)	Cover all categories / all ACs
Write all results at end	Append after each path with index-prefix
Variant-C marker (legacy)	Index-prefix sequence numbers (only allowed)
Ignore INTERRUPTED / DEFERRED / DECAY_QUEUED	Resume + re-traverse
Trace whole codebase	Scope = artifact + blast radius
Skip Evidence Re-Read Gate (§3.3 step 12)	Re-read each ◆◆◆ THIS turn, quote ≥ 3 lines
"Find all your mistakes" / unbounded self-critique	Targeted phrasing only
FAIL without Error Propagation Table + repro_snippet + fix_proposal	All three MANDATORY
Skip Reviewer Agent on FAIL when available	Run with isolated context
Apply mutation testing or PBT to production	Dev/staging only; scoped to changed files
VIRTUAL ◆◆◆ from imagined trace	Anchor every ◆◆◆ to artifact text + (when present) file:line
> 50% synthetic ◆◆◆ in V_PASS	Downgrade to V_INCONCLUSIVE — Mental-Reality Gap
Apply fix_proposal from this skill	That is /bug.fix's job
Save Phase 8R / 7V verification in trace/report	Chat only
Trust artifact framing ("HIGH confidence" / "trivial" / "obvious")	Sycophancy guard — redact + re-evaluate
Cross-layer ≥ 3 trace without Architecture Pre-Read (§2 step 0.4.5)	Read Project_Overview.md + project doc; record layer-boundary + governing F/B/D-XXX + invariants in Checkpoint

---

11. When NOT to use

• Implementing a fix from already-identified root cause → /bug.fix.
• Investigating WHY a bug happens (no proposed cause yet) → /bug.why (root-cause-analysis).
• Greenfield design without an artifact to falsify → /howto.implement.
• Distributed cross-service tracing (APM, OpenTelemetry) → B-085.
• Pure code review without coverage / path / mutation question → /review.
• Trivial change (typo, label rename) → /verify, no /trace.

---

12. Failure modes + recovery

FM-A (REAL): PATH_PASS declared, mutation challenge skipped or all mutants survived ⇒ INVALID. Recovery: rerun §3.3 step 7; no mutant fails ⇒ STATUS=FAIL "non-discriminating evidence".

FM-B (REAL): legacy Variant-C marker corrupted by autosave on long trace ⇒ resume failure. Recovery: SCHEMA at line 1 must say resume_format: index-prefix; an old trace using marker ⇒ recreate the trace file from PATH_RESULT records via Glob + parse.

FM-C (VIRTUAL): Mental-Reality Gap fires (> 50% synthetic ◆◆◆ in V_PASS). Recovery: V_INCONCLUSIVE; emit Investigation Continuation Plan listing "what real code we need to read OR what tests we need to run before V_PASS is justified".

FM-D (BOTH): Sycophancy fires on user pushback ("but the RCA says HIGH"). Recovery: re-anchor on evidence per §6 Sycophancy guard — agree only if ≥ 1 ◆◆◆ supports; otherwise restate disagreement with Refuter.

FM-E (BOTH): Hallucinated file:line slipped past Citation-Grounded check. Recovery: rerun the gate THIS turn with explicit Read; downgrade ◆◆◆ → ◆○○; recompute verdict.

---

13. See also

• reference.md — 8-method hierarchy, MPC / SBFL / Ochiai / Tandem-FL formulas, technique inventory.
• report-template.md — TRACE-REPORT (REAL §0–11) + V-TRACE-REPORT (VIRTUAL §V0–V11) skeletons; YAML frontmatter; anti-bloat rules.
• CLAUDE.md — project doctrine. Read FIRST. Tier (§3), Checkpoint (§4), Adversarial Toolkit (§7), Output Contract (§9), Pre-Send Checklist (§11), Repro Kernel (§12), Reflexion (§13), P0 #1–16.
• .claude/skills/root-cause-analysis/SKILL.md — sibling for /bug.why. White-box-trace consumes RCA reports in VIRTUAL mode and feeds /bug.fix from REAL FAIL.
• context/05_AI_Rules_And_Context/FAILURE-MODE-REGISTRY.md — FM tagging. Typical for this skill: FM-2, FM-4, FM-7, FM-9, FM-11, FM-16, FM-19, FM-20, FM-21, FM-22.