---

name: residual_logit_lens description: Apply logit-lens unembedding and additive residual contribution checks for mechanistic transformer circuit analysis.

Residual Logit Lens

Use this skill when you need to inspect how a transformer's residual stream or named additive residual components affect output logits. It is appropriate for attention-only or simplified transformer-circuit analysis where the residual stream is treated as a linear communication channel. Do not use it as a standalone causal proof when component activations are not defined.

Inputs

• A residual state matrix shaped positions x features.
• An unembedding matrix shaped features x vocabulary.
• Optional named residual components with the same shape as the residual state.

Outputs

• Full logits for every position.
• Optional per-component logits.
• A reconstruction error showing whether component logits sum to the full logits.

Workflow

1. Validate that all matrices are rectangular and dimension-compatible.
2. Compute logits = residual @ unembedding.
3. For each named component, compute component @ unembedding.
4. If components are meant to sum to the residual, compare the sum of component logits to the full logits.
5. Report the maximum absolute difference and preserve component names.

Validation

Run python tests/test_logit_lens.py or validate the full tree with:

python /share/project/yuyang/workspace/Paper2Skills/Distiller/skills/module-to-skill/scripts/validate_skill_tree.py <skill_dir> --run-tests

Limitations

This skill uses standard-library Python lists for tiny or moderate matrices. For large models, use the same contracts with a tensor library and avoid materializing unnecessary dense intermediates.