---
name: skill-l2-entry
description: L2 Knowledge Entry — retrieve prior knowledge before starting a topic, and record distilled knowledge after completing a topic phase. Three-layer retrieval: entries (Grep) → graph (MCP) → tower (MCP).
trigger: topic bootstrap, session resume, or phase completion
---

# L2 Knowledge Entry

## MANDATORY: AskUserQuestion rule

When you need to ask the user ANY question, use `AskUserQuestion`. NEVER type options as plain text.

---

## Part A: Retrieval (topic start)

Executed at topic bootstrap, session resume, or whenever the user asks "what do we know about X".

### Layer 1: Entries (MCP tool, primary)

Use `aitp_query_entries` as the PRIMARY tool for L2 knowledge retrieval:

```
aitp_query_entries(topics_root, role="claim", system="<system-slug>")
aitp_query_entries(topics_root, role="claim", status="verified")
aitp_query_entries(topics_root, role="method")
aitp_query_entries(topics_root, role="pitfall")
aitp_query_entries(topics_root, role="question")
aitp_query_entries(topics_root, query="<free text>")
```

Query patterns by use case:

| Question | Tool call |
|----------|----------|
| "What's known about system X?" | `aitp_query_entries(role="claim", system="<system-slug>")` |
| "Verified claims?" | `aitp_query_entries(role="claim", status="verified")` |
| "Known pitfalls for method X?" | `aitp_query_entries(role="pitfall", query="<method>")` |
| "What methods exist?" | `aitp_query_entries(role="method")` |
| "Open questions?" | `aitp_query_entries(role="question")` |
| "Everything about X?" | `aitp_query_l2(query="<X>")` (includes promoted candidates) |

Fallback: if `aitp_query_entries` is unavailable, use Grep/Glob:
```
Glob(pattern="L2/entries/*.md", path=$TOPICS_ROOT)
Grep(pattern="role: <target>", path="L2/entries/")
```

### Layer 2: Graph (MCP)

Query the concept graph for theoretical relationships:

```
aitp_query_l2_index(topics_root)                    → domain taxonomy
aitp_query_l2_graph(topics_root, query="<concept>") → matching nodes + edges
```

### Layer 3: Tower (MCP)

Check regime boundaries:

```
aitp_visualize_eft_tower(topics_root, tower_id="<id>")
aitp_query_l2_graph(topics_root, node_type="regime_boundary")
```

### Synthesis

Present to the researcher as:

```
PRIOR KNOWLEDGE: <system/method>
  Verified:   <list of claims with status=verified>
  Unverified: <list of claims with status=unverified or failed>
  Pitfalls:   <list of known issues>
  Questions:  <list of open questions>
  Concepts:   <relevant graph nodes>
  Regime:     <applicable tower layers>
```

This becomes the `## Prior L2 Knowledge` section in `L0/source_registry.md`.

---

## Part B: Recording (topic phase completion)

Executed after L4 validation, after a pitfall is discovered, or when the researcher explicitly asks to record.

### Entry roles and when to record

| Role | When | Mandatory facets |
|------|------|-----------------|
| **claim** | L4 pass, confirmed result, or formula derivation | `claim_type`, `statement`, `mathematical_expression`, `evidence_type` |
| **system** | First time studying this physical system | `system_type`, `formula_or_identifier`, `reference_values` |
| **method** | First time using/validating a workflow | `method_type`, `toolchain`, `steps` |
| **pitfall** | Any bug, crash, or subtle issue encountered | `symptom`, `cause`, `fix`, `affects_methods` |
| **question** | Open problem identified but not yet pursued | `question_statement`, `competing_hypotheses` |

### Entry file format

Use `aitp_create_entry` to create entries programmatically:
```
aitp_create_entry(
    topics_root=...,
    entry_id="<role>-<slug>",
    role="claim",
    title="...",
    source_ref="...",
    status="verified",
    ...
)
```

Each creation auto-rebuilds `L2/entries/INDEX.md`.

Manual entry template for reference (when MCP tools are unavailable):
Save as `L2/entries/<role>-<slug>.md`:

```markdown
---
entry_id: <unique-slug>
role: claim | system | method | pitfall | question
title: <one-line summary>
lane: [formal_theory | toy_numeric | code_method]
status: verified | consistent | unverified | failed | conjectured
regime: <when does this hold?>

# Role-specific below ---
claim_type: theorem | result | approximation | negative_result | definition | equation
statement: <the claim in one sentence>
mathematical_expression: <LaTeX if applicable>
observable: <what quantity>
evidence_type: analytic_proof | numerical | experimental | code_derived
# ... OR ...
system_type: material | hamiltonian | field_theory | lattice_model | phase | spacetime
formula_or_identifier: <chemical formula / Hamiltonian / Lagrangian>
reference_values: <known benchmarks>
# ... OR ...
method_type: numerics | analytics | experiment | code
toolchain: [<tools>]
steps: [<step1>, <step2>, ...]
# ... OR ...
symptom: <what the user sees>
cause: <root cause>
fix: <how to resolve>
affects_methods: [<method slugs>]
# ... OR ...
question_statement: <the research question>
competing_hypotheses: [<possible answers>]

source_ref: topic:<topic-slug>
updated: YYYY-MM-DD
---

# <Title>

<Human-readable explanation, prose, formulas, code snippets.>

## Relationships
- derives_from: <other-entry-id>
- verified_by: <other-entry-id>
- blocked_by: <other-entry-id>
```

### Entry quality rules

1. **status must be honest.** If a calculation failed or a formula is untested, status is `unverified` or `failed`. Never `verified` without independent confirmation.
2. **Pitfalls must be complete.** Symptom + cause + fix. Without all three, the next person can't debug.
3. **Methods must have templates.** If it's a code method and there's a working INPUT/librpa.in, embed or link it.
4. **Provenance mandatory.** Every entry must record `source_ref`.
5. **One file per fact.** Don't put unrelated claims in one file. Atomic entries are queryable; long documents are buried.

---

## Part C: Graph Operations

Beyond entries, L2 maintains a concept graph with nodes, edges, and towers.
Use these when you need structured relationships between concepts.

### Creating and updating graph nodes

For a single concept node (physics concept, theorem, technique):

```
aitp_create_l2_node(
    topics_root=...,
    node_id="<domain>-<slug>",
    title="...",
    node_type="concept",  # concept | theorem | technique | result | approximation | ...
    domain="electronic-structure",
    mathematical_expression="<LaTeX>",
    physical_meaning="...",
    source_ref="topic:<topic-slug>:L3/candidates/<slug>",
)
```

For quick concept creation when the full node metadata isn't needed yet:

```
aitp_quick_l2_concept(topics_root, title="...", domain="...")
```

To update an existing node (e.g., after L4 validation provides more evidence):

```
aitp_update_l2_node(topics_root, node_id="...", field="mathematical_expression", value="...")
```

### Creating edges

Connect nodes with typed relationships:

```
aitp_create_l2_edge(
    topics_root=...,
    source_id="<node-a>",
    target_id="<node-b>",
    edge_type="derives_from",  # see L2_EDGE_TYPES for full list
    evidence="...",
)
```

Common edge types: `derives_from`, `generalizes`, `limits_to`, `contradicts`,
`refines`, `motivates`, `dual_to`, `conjugate_to`, `falsifies`.

### EFT/Concept towers

When concepts form a hierarchy across energy/length scales:

```
aitp_create_l2_tower(
    topics_root=...,
    tower_id="<id>",
    name="...",
    energy_range="eV to GeV",
    layers=[...],
)
aitp_visualize_eft_tower(topics_root, tower_id="<id>")
```

### Merging topic subgraphs

After completing a topic phase, extract entries and merge subgraphs into global L2:

```
aitp_extract_topic_entries(topics_root, topic_slug)
```

This reads L3 candidates and L0 sources, creates draft L2 entries, and returns
what was extracted. Review each entry before merging.

```
aitp_merge_subgraph_delta(topics_root, topic_slug)
```

This merges the topic's L2 subgraph (nodes + edges + towers) into the global
L2 graph. Run after `aitp_extract_topic_entries` and human review.

---

## Part D: Provenance and Impact Analysis

### Tracing provenance

To understand where a claim came from — its full chain of derivation,
validation, and promotion:

```
aitp_get_l2_provenance(topics_root, slug="<entry-slug>")
```

Returns: source candidate, source topic, trust basis, trust scope, version history.

### Impact analysis

Before modifying or deleting an L2 node, check what depends on it:

```
aitp_query_impact(topics_root, node_id="<id>")
```

Returns: downstream nodes, edges that would break, topics that reference it.

Always run this before `aitp_update_l2_node` or manual deletion.

---

## Part E: Visualization and Cross-Reference

### Visualizing the knowledge graph

```
aitp_visualize_knowledge_graph(topics_root, domain="<domain>", query="<concept>")
```

Renders the L2 graph (or a filtered subgraph) showing nodes and edges.
Use when the human asks "show me what we know" or before presenting a
research summary.

### Finding cross-topic bridges

Search for structural isomorphisms — the same mathematical structure
appearing in different physics domains:

```
aitp_find_cross_topic_bridges(
    topics_root, topic_slug,
    expression="<LaTeX>",
    concept_name="<concept>",
)
```

A Green's function in condensed matter may have the same form as a
propagator in QFT. This tool flags these deep connections.

### Diagrams

Create and list diagrams tied to L2 nodes:

```
aitp_create_diagram(topics_root, title="...", what_it_shows="...",
    related_nodes=["<id1>", "<id2>"], source_ref="...")
aitp_list_diagrams(topics_root)
```

Diagrams are evidence attachments — they don't replace text explanations
but provide visual grounding for complex relationships.

---

## When to Use Each Part

| Phase | What to do |
|-------|-----------|
| Topic bootstrap / session resume | Part A: Query L2 for prior knowledge |
| After L4 validation (pass) | Part B: Create entries for validated claims |
| During L3 derivation | Part C: Create nodes + edges for new concepts |
| After topic phase completion | Part C: Extract entries + merge subgraph |
| Before modifying L2 | Part D: Check provenance + impact |
| Cross-domain discovery | Part E: Find cross-topic bridges |
| Research presentation | Part E: Visualize knowledge graph |
