dependency-analysis

name	dependency-analysis
description	Use when working on Phase 2 dependency mapping — internal references, external dependencies, or reference attachment. Also use when reading blob content to identify mathematical references.
allowed-tools	Read, Edit, Bash, Glob, Grep, Write

Dependency Analysis Skill

Guidance for Phase 2 work: identifying internal references, external dependencies, and reference attachment.

Internal Dependency Analysis (Stage 2.1)

Reading Blobs for References

Each blob in blobs/ contains the transcribed text of one mathematical item. When analyzing a blob for internal references:

1. Read the blob content from blobs/<chapter>/<item_id>.md
2. Identify references to other items: theorem citations, definition uses, "by Lemma X.Y.Z", "from Section X", etc.
3. Map references to item IDs using progress/items.json — match by chapter/section/number

Reference Patterns to Look For

Mathematical texts use these reference patterns:

• Explicit citations: "by Theorem 3.2.1", "see Definition 2.1.3", "from Proposition 4.5.2"
• Implicit references: "the representation defined above", "the module from the previous section"
• Notation dependencies: if a blob uses notation $V^*$ defined in an earlier item, that's a dependency
• Proof dependencies: "by the same argument as in...", "applying the result of..."

Conservative vs. Actual Dependencies

Stage 2.1 generates conservative internal dependencies (each item depends on everything before it in the same chapter). This is the initial safe baseline generated by scripts/generate_internal_deps.py.

The actual dependency trimming happens later (Stage 3.3) once proofs exist in Lean and we can analyze actual import dependencies.

Do not spend time manually trimming conservative dependencies at this stage. The tooling will do it automatically.

Validation

Use scripts/validate_dependencies.py to check dependencies/internal.json:

python3 scripts/validate_dependencies.py

This validates: no self-dependencies, no forward references (in conservative mode), all referenced items exist in items.json, valid JSON schema.

External Dependency Analysis (Stage 2.2)

What Counts as External

An external dependency is a mathematical concept the book uses but does not define or prove. Examples:

• "Let $V$ be a finite-dimensional vector space" — assumes linear algebra
• "By Maschke's theorem" (if stated without proof in the book)
• Standard facts from group theory, ring theory, module theory assumed as prerequisites

Categories

External dependencies fall into categories:

• linear_algebra — vector spaces, linear maps, tensor products, dual spaces
• group_theory — group actions, representations, characters
• ring_theory — algebras, modules, ideals
• analysis — topology, measure theory (rare in this book)
• combinatorics — partitions, Young diagrams
• category_theory — functors, natural transformations

Validation

Use scripts/validate_external_deps.py to check dependencies/external.json:

python3 scripts/validate_external_deps.py

Work Patterns

Batch by Chapter

Process dependencies one chapter at a time. Each chapter's blobs are independent enough to analyze separately, and the chapter structure is already established in items.json.

Validate Early

Run validation scripts after each chapter's dependencies are added, not at the end. This catches formatting errors and missing references immediately.

Cross-Chapter References

Some items reference definitions or results from other chapters. When you encounter a cross-chapter reference:

1. Note both the source item and the target item
2. Verify the target item exists in items.json
3. Add the dependency to dependencies/internal.json

Cross-chapter references are the most error-prone — double-check item IDs carefully.