# DEPTH=reference vs DEPTH=study in Book-to-Skill: Key Differences Explained

> Understand DEPTH=reference vs DEPTH=study in Book-to-Skill. Learn how reference provides quick insights and study offers deep understanding for effective learning.

- Repository: [Virgilio Junior/book-to-skill](https://github.com/virgiliojr94/book-to-skill)
- Tags: deep-dive
- Published: 2026-08-29

---

**DEPTH=reference generates lean, fast-lookup chapters with 800–1,800 tokens for quick decision-making, while DEPTH=study produces expansive, example-driven chapters with 1,000–3,000 tokens for deep learning.**

Book-to-Skill, an open-source project maintained by virgiliojr94/book-to-skill, uses the **DEPTH** variable to control the granularity of generated skill chapters. Understanding the difference between `DEPTH=reference` and `DEPTH=study` is essential for optimizing token usage and ensuring the generated content matches your intended use case, whether you need quick reference material or comprehensive study guides.

## Content Structure: Reference vs Study Mode

The DEPTH variable determines how much pedagogical content is included in each generated chapter. This setting is automatically inferred from the user's answer to the "purpose" question in Step 4 of the generator pipeline, as documented in [`docs/architecture.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/docs/architecture.md) (lines 33–35).

### DEPTH=reference (Quick Lookup Mode)

**Reference depth** is optimized for speed and minimal token consumption. Chapters generated in this mode contain only essential decision-ready points, omitting worked examples, expanded procedural steps, and deep reasoning. The resulting content is compact and loads faster, making it ideal for scenarios where you need to look up specific facts or commands without narrative context.

### DEPTH=study (Deep Learning Mode)

**Study depth** prioritizes pedagogical richness over brevity. These chapters include concrete worked examples, expanded "how" steps, and brief "why it works" notes. According to the specification in [`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md) (lines 45–51), study mode adds "## Worked Example" sections and actionable content that learners can reproduce, providing a more thorough understanding at the cost of higher token usage.

## Token Budget Matrix

The concrete difference between the two modes is enforced through a token budget matrix defined in [`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md). The allocation varies by both DEPTH setting and book type (`text` or `technical`), with technical books receiving higher limits to accommodate code examples and technical specifications.

| Book Type | DEPTH=reference | DEPTH=study |
|-----------|----------------|-------------|
| **text** | 800–1,200 tokens | 1,000–1,800 tokens |
| **technical** | 1,200–1,800 tokens | 2,000–3,000 tokens |

Technical books consistently require 40–66% more tokens than text books at the same depth level due to the inclusion of syntax, configuration examples, and command references.

## Implementation in the Source Code

The DEPTH logic is implemented across several core files in the repository. The mapping of user intent to DEPTH value is specified in [`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md) (lines 91–95), while the budget enforcement resides in the configuration layer.

### Book Type Configuration

Supported book types are defined in [`book_to_skill/config.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/config.py), where valid entries include `text` and `technical`. These types combine with the DEPTH variable to compute the final token constraints passed to the language model.

### Budget Calculation Logic

The token allocation is implemented programmatically using a dictionary mapping that corresponds to the matrix in [`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md):

```python

# Token budget matrix as defined in the configuration

DEPTH_BUDGET = {
    ("text", "reference"): (800, 1200),
    ("text", "study"):     (1000, 1800),
    ("technical", "reference"): (1200, 1800),
    ("technical", "study"):     (2000, 3000),
}

def token_budget(book_type: str, depth: str) -> tuple[int, int]:
    """Retrieve min and max token limits for a given book type and depth."""
    return DEPTH_BUDGET[(book_type, depth)]

```

### Depth Inference Algorithm

The system automatically infers DEPTH from the user's answer to the purpose question in Step 4. A simplified representation of this logic, as implemented in the CLI orchestration layer ([`book_to_skill/cli.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/cli.py)), follows this pattern:

```python
def infer_depth(answer: str) -> str:
    """
    Determine DEPTH based on user selection.
    '3' maps to reference mode; all others default to study.
    """
    opts = set(answer.split())
    return "reference" if opts == {"3"} else "study"

```

## When to Use Each Mode

**Choose DEPTH=reference** when building quick-reference cards, command cheat sheets, or API documentation where the goal is fast lookup and minimal token costs during querying.

**Choose DEPTH=study** when creating onboarding materials, tutorial documentation, or training resources where the reader needs to understand not just *what* to do, but *how* and *why* through concrete examples.

## Summary

- **DEPTH=reference** produces lean chapters (800–1,800 tokens) optimized for fast lookup, omitting worked examples and deep reasoning to minimize token consumption.
- **DEPTH=study** generates comprehensive chapters (1,000–3,000 tokens) including concrete worked examples, expanded procedural steps, and pedagogical context for deep learning.
- The mode is determined in **Step 4** of the generator pipeline based on the user's purpose answer, as documented in [`docs/architecture.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/docs/architecture.md) and specified in [`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md).
- Token budgets are enforced through the `DEPTH_BUDGET` mapping in the configuration layer, with technical books receiving higher allocations than text books at both depth levels.

## Frequently Asked Questions

### How is DEPTH automatically determined in Book-to-Skill?

DEPTH is set during Step 4 of the generation pipeline based on the user's answer to the "purpose" question. According to the architecture documentation in [`docs/architecture.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/docs/architecture.md) (lines 33–35), selecting option "3" maps to `reference` mode, while any other selection defaults to `study` mode. This logic is implemented in the CLI orchestration layer within [`book_to_skill/cli.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/cli.py).

### What are the exact token limits for each DEPTH setting?

The token budgets are hardcoded in [`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md) (lines 45–51) and implemented in the configuration module. For text books, reference mode allows 800–1,200 tokens and study mode allows 1,000–1,800 tokens. For technical books, reference mode allows 1,200–1,800 tokens and study mode allows 2,000–3,000 tokens.

### Does DEPTH affect the presence of worked examples?

Yes. DEPTH=study explicitly includes "## Worked Example" sections and expanded "how" steps that are strictly omitted in DEPTH=reference. The [`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md) specification (lines 45–51) states that reference mode provides only "essential decision-ready points" without the concrete examples and reasoning steps included in study mode.

### Where is the DEPTH logic implemented in the source code?

The DEPTH behavior is distributed across three key files: [`docs/architecture.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/docs/architecture.md) defines the Step 4 mapping, [`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md) contains the semantic specification and token matrix (lines 45–51 and 91–95), and [`book_to_skill/config.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/config.py) defines the supported book types. The runtime application of these budgets occurs in [`book_to_skill/cli.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/cli.py), which orchestrates the extraction and generation flow.