---
name: header-cycle-breaker
description: Guide for breaking cyclic dependencies in V8 headers and resolving cascade IWYU failures.
---

# Header Cycle Breaker Skill

This skill outlines the systematic approach to breaking cyclic dependencies in
V8 headers, specifically focusing on moving heavy inline includes to more
localized `.cc` files or non-inline headers, and resolving the resulting cascade
of "undefined inline function" errors (IWYU - Include What You Use style).

## When to Use

Use this skill when:

- You are tasked with breaking a header cycle in V8 (e.g., core-to-wasm cycle).
- You need to remove an `-inl.h` include from another `-inl.h` or `.h` file.
- You encounter a flood of `[-Werror,-Wundefined-inline]` errors after modifying
  a heavy header.

## Workflow

### Phase 1: Identification and Cycle Breaking

1. **Identify the cycle**: Use tools or subagents to map the include graph and
   find the cyclic path.
2. **Plan the break**: Identify a point where an `-inl.h` can be replaced with
   its non-inline counterpart (`.h`) or where an include can be moved entirely
   to implementation files.
3. **Apply the break**: Modify the header file to break the cycle.

### Phase 2: Resolving the Cascade (IWYU)

Breaking a heavy include chain will cause many implementation files (`.cc`) and
even generated files to fail because they were relying on transitive includes
for inline definitions.

1. **Do not panic**: Expect tens or hundreds of compilation errors initially.
2. **Aggressive Delegation**: Spawn subagents for independent file failures.
   Prompt them to identify missing headers for specific undefined symbols.
3. **IWYU Application**: For each failing file:
   - Identify which inline method is undefined.
   - Find which `-inl.h` file defines it.
   - Include that `-inl.h` file directly in the failing `.cc` file, preferably
     within appropriate guards (e.g., `#if V8_ENABLE_WEBASSEMBLY`).
4. **Repeat until clean**: Build, fix, and build again. This is an iterative
   process.

### Phase 3: Special Case - Generated Files

If a generated file (e.g., `objects-printer.cc`) fails with undefined inline
methods:

1. **Trace to generator**: Realize that editing the generated file is temporary.
   Find the source generator (e.g., in `src/torque/`).
2. **Modify the generator**: Update the generator code to emit the necessary
   `#include` statements in the files it generates.
3. **Rebuild the generator**: Recompile the tool (e.g., Torque) and let the
   build system regenerate the files.

## Best Practices

- **Keep files isolated**: Do not revert the cycle-breaking change when you see
  cascade errors. Push through by fixing the files.
- **Use guards**: Always wrap Wasm-specific includes in
  `#if V8_ENABLE_WEBASSEMBLY`.
- **Check trait caching**: Be aware of C++ trait caching issues if you encounter
  weird subtyping errors during header reorganization.