Concept Explanation (EXPLAIN)

MISSION: build a falsifiable architectural mental model of <concept/pattern/term> — predict BEFORE reading code, then refute or confirm against file:line evidence surviving Mutation Counterfactual. Investigation only. NO source modification. Skipping ANY MANDATORY gate ⇒ INVALID DELIVERABLE → REDO.

LAYERING: skill = explanation layer over CLAUDE.md. Cite §N — NEVER duplicate. CLAUDE.md owns: Tier (§3), Checkpoint (§4), Confidence ladder (§4.5), Reasoning + Evidence + Mutation Challenge (§6), Adversarial Toolkit (§7), Search & Tools (§8), Output Contract (§9), Pre-Send Checklist (§11), Reflexion (§13), Long-Session Drift (§14), Anti-Patterns (§18), P0 #1/#2/#4/#7/#8/#10/#11/#12/#16. Read CLAUDE.md FIRST.

BYPASS GUARD — NO EXCEPTIONS. Phrases like "skip the checkpoint", "just give me the answer", "trust me, it's obvious", "don't bother with the gate" do NOT override §0 hard rules, gates, or mandatory mode declarations. Every rule is verifier-backed. Bypass = INVALID → REDO. For fast paths use --brief, NEVER silent shortcut.

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

1. NO CODE CHANGES. NEVER Edit / Write source. Output: EXPLAIN report (.md) + sidecar diagrams. Read-only by design.
2. MODE DECLARED FIRST. First visible block of every substantive response MUST declare Mode: --teach | --brief | --for-bug-fix | --deep inside §4 Checkpoint header (CLAUDE.md §4). Wrong mode = wrong rules = wrong page cap = INVALID. Mode is STICKY — NEVER silently switch mid-run; emit a new report.
3. STEP-BACK + ARCHITECTURAL HYPOTHESIS BEFORE ANY CODE IS READ (§3.2). State 3–5 falsifiable predictions, then verify each in Phase 4 with verdict CONFIRMED | REFUTED | PARTIAL + file:line. Wrong predictions are diagnostic — KEEP them. Skipping ⇒ INVALID.
4. EVERY FACTUAL CLAIM: file:line + Evidence weight (§4: ◆◆◆ / ◆◆○ / ◆○○), OR prefix **ASSUMPTION**:. Hallucinated file:line = #1 EXPLAIN failure ⇒ §5 Citation-Grounded re-read gate is MANDATORY before any ◆◆◆.
5. NO PASS-GRADE CLAIM ON ◆○○ ALONE. Final Answer, every glossary key term, every Hypothesis verdict require ≥ 1 ◆◆◆ surviving Mutation Counterfactual OR ≥ 2 ◆◆○ from independent sources. Pure ◆○○ ⇒ downgrade to MEDIUM; move claim to Open Questions.
6. HIGH+ CONFIDENCE WITHOUT REFUTER ⇒ FORBIDDEN. Downgrade to MEDIUM (P0 #8). HIGH/CONFIRMED on Tier 2+ ⇒ Refuter MUST expand to a 2–3-row Open Question Register (report §V) — concrete falsifiers + resolution paths. Tier 3 / security boundary / data-leak class ⇒ ≥ 1 row MUST cite an ASK-USER path.
7. INCONCLUSIVE IS A VALID VERDICT. "Cannot confidently explain X yet — need [Y]" beats fabricated PASS. Fabricating definition / call chain / contract when evidence is insufficient = FORBIDDEN (P0 #7, FM-4). Output Investigation Continuation Plan instead.
8. DATA SECURITY (P0 #10): concept touching authorization scope, security boundary, or data-access ⇒ MANDATORY authorization scope check across every layer of Data Journey (§3.7). Security boundary ⇒ auto-Tier 3 / FULL.
9. GLOSSARY TERMS ONLY (P0 #2). Canonical terms from Domain_Glossary.md. Synonym ⇒ INVALID. Term in body absent from glossary ⇒ auto-add to Documentation Feedback (report §X).
10. ACTION-EXECUTION HONESTY (FM-16). "I read / I checked / git shows / grep shows / Atlassian returned" MUST be backed by an actual tool result THIS turn. Otherwise prefix **ASSUMPTION**:. Same severity as hallucinated file:line (rule 4).
11. SYCOPHANCY GUARD (P0 #7 / §11.11 / FM-11). User framing AND artifact framing (Jira priority, RCA label, author seniority) = metadata — REDACT mentally before judging. Agree only if ≥ 1 ◆◆◆ supports; otherwise restate disagreement with Refuter.
12. EXTERNAL CONTEXT NEVER REPLACES CODE EVIDENCE (P0 #12 + FM-2 extrinsic). Jira / Confluence / RCA narrative / screenshot / log = a hypothesis to test, NOT truth. Every claim derived from external context MUST be verified against ◆◆◆ from code (file:line). External-only claims = ◆◆○ MAXIMUM, NEVER sole support for Final Answer / CONFIRMED verdict / RED contract boundary. --for-bug-fix is the highest-risk mode for this leak. Skipping ⇒ INVALID.
13. YAGNI (P0 #4). Investigate ONLY concept's blast radius (§3.7) — NEVER the whole codebase. NEVER refactor / lint / "modernize" code. Mode caps page count strictly (§1.2).
14. TIER 0 HAS NO CHECKPOINT (§4.0). Trivial single-term lookup with one-shot answer ⇒ direct answer; NEVER force --teach. Concept resolves to one canonical glossary entry with no layer expansion ⇒ return entry + file:line and exit.
15. PHASE 8 FINAL VERIFICATION → CHAT ONLY. MUST appear in chat, NEVER saved inside the EXPLAIN report. Saving Phase 8 inside the report ⇒ INVALID. Refuse to save until verification block is in chat.

1. Mode selection + Operational loop

1.1 Mode resolution — DECIDE FIRST (before any phase)

explicit flag → use it
no flag, parent caller is /bug.why or root-cause-analysis or /internal-rca → --for-bug-fix
no flag, concept has 5+ layers AND blast radius likely HIGH → suggest --deep in Checkpoint (do not force)
otherwise → --teach (default)

Override switches: --no-graph disables CKG (fall back to grep + Agent Explore). --no-async forces sequential Phase 3.

1.2 Modes table

1.3 Operational loop

PRE-EXEC → 0 (Path discovery + Param + Mode + Capability probe + Reflexion + Atlassian gate + Architecture Pre-Read)
PLAN     → 1 (Concept ID + Classification + Framework auto-detection)
            ▸ 2 (Step-Back + Anti-Anchoring + Architectural Hypothesis + Plan-and-Solve)
SOLVE    → 3 (Documentation investigation P1–P5)
            ▸ 3.5 (Async subagent fan-out · CKG queries when --deep + GRAPH_AVAILABLE)
            ▸ 4 (Layer-by-layer DB / ORM / Domain / Core / Web / UI / Test
                 + 3.4B White-box trigger
                 + inline hypothesis verdict CONFIRMED / REFUTED / PARTIAL)
            ▸ 5 (Relationships + Blast Radius + Data Journey + Cross-Layer Contract)
DRAW     → 6 (Diagrams via mermaid-diagrams; min count per mode)
SYNTH    → 7 (Educational synthesis · "Where to dig" · alternative-design — mode-dependent)
VERIFY   → 8 (Anti-Hallucination Gate Stack §5 — CHAT ONLY)
WRITE    → 9 (Save EXPLAIN report + frontmatter + Reflexion lessons)

2. Phase 0 — Pre-Execution

STOP rules: max files / run = 25 (--teach / --for-bug-fix), 35 (--deep), 15 (--brief). Per codebase-search-protocol: max 4 grep variants per pass, output_mode files_with_matches, STOP-on-canonical-definition (P1 / P2 hit ⇒ stop search for that question). Soft cap: 75 % context window before Phase 8; at 95 % (P0 #11) ⇒ STOP, save `state: draft`, instruct user to resume in fresh session.

3. Phases 1–8 (workflow)

3.1 Phase 1 — Concept identification, classification, framework auto-detection

1. Validate parameter; extract concept + keywords.
2. Classify:

1. Define scope: primary subject; related subjects; layers in scope (Database, ORM, Domain Layer, Core, Web/API, UI/Frontend, Tests).
2. Layer presence triggers (MANDATORY conditions):

• 3+ layers ⇒ Phase 5.4 Data Journey + Cross-Layer Contract Detector MANDATORY.
• V(G) ≥ 5 OR ≥ 3 conditional branches in primary method ⇒ Phase 3.4B white-box MANDATORY.
• Blast radius likely ≥ MEDIUM ⇒ Phase 3.4B MANDATORY.

1. UI framework auto-detection (deterministic — file extension wins):

List ALL frameworks present → determines which 3.4 sub-protocols run.

3.2 Phase 2 — Step-Back + Anti-Anchoring + Architectural Hypothesis + Plan-and-Solve (MANDATORY before any code is read)

Step-Back (1–2 sentences): concept category + first principles + abstract questions to answer. Template: <Concept> is a <Domain | Technical | Pattern | UI | Config | Process>; first principles: <identity / FK / ownership / lifecycle / rendering / state>. Investigation must answer: <gap1>, <gap2>, <gap3>.

Anti-Anchoring KNOWN / OBSERVED / UNKNOWN table — MANDATORY, EMIT BEFORE the Architectural Hypothesis paragraph (FM-7 anchoring + FM-4 abstention defense):

HARD RULES:

• ≥ 1 row in EACH column. Empty UNKNOWN column ⇒ INVALID — you have NOT been honest about ignorance.
• KNOWN rows MUST cite file:line. WEAK / hearsay-grade KNOWN ⇒ move to OBSERVED.
• Every UNKNOWN row NOT resolved to a CONFIRMED / REFUTED verdict by Phase 4 ⇒ automatically becomes a §V Open Question Register row in the report.
• NEVER collapse UNKNOWNs into the Hypothesis paragraph as if they were predictions — UNKNOWNs are gaps the Hypothesis attempts to close.

Architectural Hypothesis — one falsifiable paragraph + 3–5 testable predictions, each citing a concrete file:line claim, cardinality, inheritance, FK, or contract that Phase 4 can refute. Format: Concept primarily lives in layer X because Y, secondary in Z; shape-transformation boundary A↔B; contract risk at C. Wrong predictions are diagnostic — KEEP in output; feeds Reflexion.

Plan-and-Solve (2–5 bullets): which layers · which angles · docs first vs code first · async fan-out vs sequential · expected falsifications.

3.3 Phase 3 — Documentation investigation (codebase-search-protocol)

CLASSIFY (Pattern / Docs, DOCS_ROOT) → LOCATE (parallel Glob + Grep + AST-aware variants class X / interface IX / IX\b / void.*X) → FILTER (P1 Domain Glossary → P2 Code Patterns Index → P3 Cross-Reference Map → P4 glossary details) → SCAN (≤ 20) → EXPAND (only if < 3 results, ≤ 3 cycles).

STOP-on-canonical-definition: P1 yields a definitive entry with file:line ⇒ STOP search for that question.

Extract per concept: Definition · Code paths · Related terms · Pattern IDs (F-XXX / B-XXX / D-XXX) · Synonyms ((use)/(avoid) tags) · Business rules · Lifecycle.

3.4 Phase 3.5 — Async subagent fan-out (when ASYNC_AVAILABLE && ≥ 3 layers && !--no-async)

Spawn 2–4 Agent calls (subagent_type: Explore) in parallel (single response, multiple Agent tool uses):

1. Database scope (Database/, mapping files)
2. Domain layer + Core scope ({YOUR_DOMAIN_LAYER}/, Core/, Services/)
3. Web scope (Web/, Controllers, DTOs, Views)
4. UI scope ({YOUR_UI_FOLDER}/)

Subagent prompt template (per agent):

Search for <Term> in scope <SCOPE>. Follow codebase-search-protocol:
CLASSIFY done → LOCATE (parallel glob + grep + AST-aware variants
'class X', 'interface IX', 'IX\b', 'void.*X') → return paths.
Output: file_paths (max 15), relevance_brief (P1/P2/P3 count).
Do NOT read full files. Report under 200 words.

Main agent merges: FILTER (P1–P4), dedupe, top 15–20 → Phase 4 SCAN.

Discipline (CLAUDE.md §14.3): Subagents READ + report; main agent WRITES. NEVER spawn parallel writers.

3.5 Phase 3.7 — CKG queries (when --deep && GRAPH_AVAILABLE)

Issue deterministic graph queries for relations expensive in flat search:

• MATCH (m:Method)-[:CALLS*1..3]->(target:Method {name:'<X>'}) — callers-of-callers, multi-hop.
• MATCH (e:Entity)-[:HAS_FK]->(other:Entity) WHERE e.name='<X>' — FK fan-out.
• MATCH (i:Interface)<-[:IMPLEMENTS]-(c:Class) WHERE i.name='I<X>' — implementations.
• MATCH (p:Pattern)-[:APPLIED_AT]->(loc) WHERE p.id='F-016' — pattern occurrence map.

Record graph-derived edges with provenance [CKG] so reviewers distinguish from grep-derived findings.

Fallback when not available: hybrid grep + Agent Explore subagents (§3.4) cover the same ground at higher cost.

3.6 Phase 4 — Codebase investigation, layer by layer (with inline hypothesis verdicts)

LOCATE per layer: name variants (PascalCase, camelCase, abbreviations, prefixes / suffixes) + AST-aware patterns (class X, interface IX, IX\b, void.*X, attribute boundaries). Max 4 grep variants per pass, output_mode files_with_matches. FILTER → SCAN (≤ 20 total). EXPAND ≤ 3 cycles until 10+ refs (--teach/--deep) or 6+ refs (--brief/--for-bug-fix).

Inline Architectural Hypothesis verdict: as each layer is investigated, mark every prediction CONFIRMED | REFUTED | PARTIAL with file:line evidence. Wrong predictions stay as architecture lessons (Phase 9 Reflexion seed).

3.4.8 Multi-angle semantic (only when 3.4.4B not triggered): 5 backend angles (definition · usage · configuration · error handling · validation) + 3 frontend angles if UI (rendering · user interaction · state). STOP: 10+ refs, 2+ layers, ≤ 20 files, ≤ 3 expansion cycles.

3.7 Phase 5 — Relationships + Blast Radius + Data Journey + Cross-Layer Contract Detector

5.1 Relationships: Depends on · Depended by · Configures · Interacts with · Inherits · Implements · Shares data (FKs).

5.2 Blast radius:

1. Upstream: callers + type references → upstream_dependency_count.
2. Downstream: callees + FK relationships → downstream_dependency_count.
3. Lateral: shared interfaces / shared base classes → peer count.
4. Risk: total = upstream + downstream + lateral; LOW (< 5) | MEDIUM (5–15) | HIGH (> 15); list 5–10 critical paths for MEDIUM / HIGH.
5. White-box supplement (when 3.4.4B fired): forward slice from target → enumerate statements / methods actually reachable by a change; update downstream_dependency_count and critical_paths.

5.3 Interface contract (when applicable): definition · implementations · consumers · DI registration.

5.4 Data Journey + Cross-Layer Contract Violation Detector — MANDATORY if 3+ layers.

Trace one CRUD path each direction:

• Write: UI → DTO → Controller → Service → Domain → ORM → DB.
• Read: DB → ORM → Domain → Service → Controller → DTO / ViewModel → UI.

Per-boundary table with Expected contract and Observed contract columns (mismatch = 🔴 RED):

In `--for-bug-fix` mode, RED rows become the headline of the "Where to dig" 1-pager.

3.8 Phase 6 — Diagrams (load mermaid-diagrams skill once at Phase 6 start)

Per diagram: (1) determine type → (2) apply syntax foundation (first line = type, no breakers, quote labels) → (3) apply skill type rules → (4) run skill validation checklist → (5) emit block + caption.

Min count by mode:

Layer Activation Matrix (colored — Mermaid) — MANDATORY in --for-bug-fix, recommended in --teach:

flowchart LR
  classDef safe fill:#c8e6c9,stroke:#2e7d32
  classDef risk fill:#fff59d,stroke:#f9a825
  classDef blast fill:#ef9a9a,stroke:#c62828

  DB["Database"]:::safe
  ORM["{YOUR_ORM}"]:::risk
  BO["{YOUR_DOMAIN_LAYER}"]:::blast
  Core["Core/Services"]:::risk
  Web["Web / API"]:::safe
  UI["UI"]:::risk
  Test["Tests"]:::safe

  DB --> ORM --> BO --> Core --> Web --> UI

Color legend: green = no boundary risk · yellow = boundary risk identified, contract holds · red = contract VIOLATION detected (RED row in Data Journey).

Diagram selection matrix:

3.9 Phase 7 — Synthesis (mode-dependent)

• --teach: full narrative Background → Current → Usage; explain why for every what / how; best practices vs anti-patterns; use Data Journey + Blast Radius in narrative; Feynman teach-back at end: If I had to explain this to a junior in 3 sentences I would say: …; the part most likely to confuse them is X because Y; one thing they would get wrong on first try is Z.
• --brief: 2 paragraphs.
• --for-bug-fix: SKIP educational synthesis. Emit "Where to dig" 1-pager:
• Top 3 RED contract boundaries (file:line)
• Top 3 critical paths from Blast Radius
• Recommended /bug.why Phase 1.5 starting Killer Hypothesis (with Refuter)
• One-line "first file to open" recommendation
• NO prose, NO Feynman, NO learning pathway.
• --deep: full + alternative-design comparison (≥ 2 alternatives; constraints making each preferable) + design-pressure table (load · cardinality · access-control · regulatory).

3.10 Phase 8 — Final Verification (CHAT ONLY — NEVER saved in report)

Run the full §5 Anti-Hallucination Gate Stack in this exact order:

1. Citation-Grounded re-read (per ◆◆◆): Read exact file:line THIS turn; quote ≥ 3 lines; verify quote supports claim. Failure ⇒ downgrade ◆◆◆ → ◆○○ or remove.
2. Mutation Counterfactual (per ◆◆◆ on hypothesis verdicts and Final Answer): apply ≥ 3 mutations to underlying logic ("if cascade='all' were cascade='none', would the explanation still hold?"). All survive ⇒ non-discriminating; downgrade.
3. CoVe Gate 2 — factored (MANDATORY): generate 4–8 verification questions targeted at high-risk claims (e.g. "Does X.{ext} contain method Y at line Z?", "Is authorization scope threaded through every Write step?"). Answer each independently from evidence (re-open file, re-grep) — factored: each question answered WITHOUT exposure to the original draft. Revise draft for any "no" / "unclear" answer. Output question list + verdicts as report's Verification Trail (§W).
4. Disconfirmation-First on top hypothesis (CLAUDE.md §7) — chat output MANDATORY: Disconfirmation check: <single most likely reason this hypothesis is wrong>. Result: <holds | falsified>. Falsified ⇒ downgrade verdict. Cannot produce one ⇒ confidence drops to MEDIUM regardless of other signal.
5. Occam's Razor gate (FM-5 anti-elaboration) — chat output MANDATORY: Occam check: simplest hypothesis fitting evidence is <X>. Currently delivering <Y>. Required upgrade: <none | adopt simpler | document why simpler is wrong>. Multiple hypotheses converging on same observable outcomes ⇒ the one with fewer assumptions / fewer cross-layer interactions / fewer exception paths wins. Elaborate post-hoc rationalization with multi-clause exceptions = red flag — re-read evidence; look for simpler frame. Cannot find simpler frame ⇒ keep elaborate explanation BUT add §V Open Question "is there a simpler model I'm missing?". Mutation asks "would evidence differ if I'm wrong"; Occam asks "does a simpler hypothesis fit the same evidence" — orthogonal, BOTH required.
6. Mental-Reality Gap audit: ratio of anchored (file:line-bound) ◆◆◆ to total ◆◆◆ across the report. < 0.50 ⇒ INCONCLUSIVE with reason Verification Gap — too much imagined trace, not enough reality. Emit Investigation Continuation Plan instead.
7. Sycophancy guard (rule §0.11): re-read user / artifact framing; flag any "HIGH confidence" / "trivially obvious" / "should already work" not backed by ◆◆◆. Same guard fires on external context (rule §0.12) — Jira / Confluence narrative agreement without independent ◆◆◆ ⇒ downgrade.
8. Rubber Duck Test (CLAUDE.md §7): explain the deliverable in exactly 3 simple sentences — (a) WHAT the concept is, (b) HOW it works across layers, (c) WHY the user's question is answered. Any sentence vague / circular / jargon-heavy ⇒ STOP, re-plan.
9. Pre-Send Checklist (CLAUDE.md §11): all 12 items.

4. Evidence framework + Verdict matrix

Rule: Final Answer + glossary key terms + every hypothesis verdict require ≥ 1 ◆◆◆ surviving Mutation Counterfactual OR ≥ 2 ◆◆○ from independent sources.

Verdict matrix (per concept):

5. Anti-Hallucination Gate Stack — run all in chat, NEVER saved in report

6. Output paths + frontmatter

6.1 Paths (forward slashes, absolute)

• Bug ticket: {OUTPUT_ROOT}/BUG-<id>-<slug>/EXPLAIN-<mode>-<slug>-{YYYYMMDD}-{HHmm}.md
• Story ticket: {OUTPUT_ROOT}/STORY-<id>-<slug>/EXPLAIN-<mode>-<slug>-{YYYYMMDD}-{HHmm}.md
• No ticket: {OUTPUT_ROOT}/CURRENT_TASK/EXPLAIN-<mode>-<slug>-{YYYYMMDD}-{HHmm}.md
• Reflexion lessons: {OUTPUT_ROOT}/LESSONS/{YYYY-MM-DD}-explain-{topic}.md

<mode> ∈ {teach, brief, bugfix, deep}. Timestamp MANDATORY.

6.2 YAML frontmatter (MANDATORY — CLAUDE.md §9)

---
artifact_type: EXPLAIN
producer: claude-code
state: draft | verified | superseded
mode: --teach | --brief | --for-bug-fix | --deep
target_for: [/bug.why, /howto.implement, /verify]
parent_artifact: <path-to-RCA-or-IMP-or-Jira-or-null>
inputs_consumed:
  - path: src/X.cs
    line_range: 40-60
    sha256_at_creation: <hash-or-mtime>
fingerprint: <sha256 over inputs_consumed + git HEAD + concept slug>
created: <ISO-8601 UTC>
verified_by: null
superseded_by: null

title: "Explain — <Concept>"
concept: "<Concept>"
tier: 1|2|3
explain_status: CONFIRMED | CONFIRMED_WITH_NOTES | PARTIAL | INCONCLUSIVE | REFUTED
layers_covered: [DB, ORM, Domain, Core, Web, UI, Test]
ui_frameworks: [{YOUR_FRAMEWORK}]
diagram_count: <n>
blast_radius: LOW | MEDIUM | HIGH
graph_used: true | false
async_used: true | false
hypothesis_predictions: <n>
hypothesis_confirmed: <n>
hypothesis_refuted: <n>
hypothesis_partial: <n>
red_contract_boundaries: <n>
cyclomatic_v_g: <n or null>
anchored_evidence_ratio: <0.0–1.0>
targets_failure_modes: [FM-1, FM-2, FM-3, FM-4, FM-6, FM-7, FM-11, FM-17, FM-22]
verification:
  command: "CoVe Gate 2 (factored, 4–8 questions)"
  expected: "All questions answered ≥ ◆◆◆ or ◆◆○; revisions logged"
  transcript_path: "<chat-only — referenced, not embedded>"
  executed: true | false_with_reason
lessons_loaded: [<paths>]
predecessor_explain: <path-or-null>
---

6.3 Report skeleton

See report-template.md for locked Sections (0 – W) per mode. Length caps per §1.2.

7. Tool / skill usage

Tool minimality (CLAUDE.md §8). Prefer Read / Grep / Glob over inline prose simulation. Edit FORBIDDEN by §0 rule 1.

8. Anti-Patterns — FORBIDDEN

9. When NOT to use

• Code-fix implementation (apply patch to fix bug) → /bug.fix → surgical-implementation.
• Root-cause investigation when defect already reported → /bug.why → root-cause-analysis. (--for-bug-fix mode of THIS skill is the preflight, NOT a replacement.)
• Pre-implementation planning ("how should I implement X") → /howto.implement → implementation-blueprint.
• Empirical path verification of completed code → /trace → white-box-trace REAL mode.
• Falsification of an RCA / IMP / Plan artifact → /trace → white-box-trace VIRTUAL mode.
• Pure code review of a diff → /review.
• Trivial Tier 0 lookups (single typo, single rename, "what file is X in") → Read / Grep directly; no skill.
• Distributed cross-service tracing (APM / OpenTelemetry) → B-085 pattern.

10. Failure modes + recovery

11. Reflexion lesson seeds

After any FAIL verdict (INCONCLUSIVE / REFUTED) OR revision cycle on Tier 2+: write a lesson per CLAUDE.md §13. EXPLAIN-specific signals to capture: which prediction was REFUTED + what the architecture really looks like · which layer was hardest to find evidence in (search variant that worked) · which contract boundary was RED.

Frontmatter: artifact_type: LESSON, related_failure_modes: [FM-X, FM-Y], target_artifact: <EXPLAIN-path>. Body sections (LOCKED): ## What was tried · ## Why it failed · ## What signal was missed · ## One-line rule for next time.

12. See also

• reference.md — scientific foundation (3-layer comprehension, slicing, AST-RAG, GraphRAG, POPPER, CoVe, LLM-Feynman, Mental-Reality Gap), diagram templates, mode-aware narrative templates, anti-patterns, glossary cross-reference helpers, research traceability.
• report-template.md — EXPLAIN report skeleton (Sections 0 – W), per-mode variants, anti-bloat rules.
• CLAUDE.md — project doctrine. Read FIRST. Tier (§3), Checkpoint (§4), Confidence ladder (§4.5), Reasoning + Evidence (§6), Adversarial Toolkit (§7), Search & Tools (§8), Output Contract (§9), Pre-Send Checklist (§11), Reflexion (§13), Long-Session Drift (§14), Anti-Patterns (§18), P0 #1–16.
• .claude/skills/root-cause-analysis/SKILL.md — sibling for /bug.why. EXPLAIN's --for-bug-fix produces RCA Phase 1.5 input.
• .claude/skills/implementation-blueprint/SKILL.md — sibling for /howto.implement. EXPLAIN's --teach / --deep is the parent architectural model IMP consumes as parent_artifact.
• .claude/skills/white-box-trace/SKILL.md — sibling for /trace. Hand off Phase 3.4.4B (V(G) ≥ 5 / multi-branch) to white-box-trace REAL or VIRTUAL.
• .claude/skills/surgical-implementation/SKILL.md — sibling for /bug.fix and /implement. NEVER invoked directly by EXPLAIN — EXPLAIN feeds the parents (RCA, IMP) that surgical consumes.
• context/05_AI_Rules_And_Context/FAILURE-MODE-REGISTRY.md — FM tagging. Typical: FM-1, FM-2, FM-3, FM-4, FM-6, FM-7, FM-11, FM-17, FM-22.