---
name: vne-header-hygiene
description: >
  Enforce include ordering, header self-containment, and forward-declaration
  rules. Use this skill when adding or editing #include / #import directives or
  creating C++ / Objective-C++ headers in a VertexNova repository.
---

# Header Hygiene

Rules for includes and headers in VertexNova. Each repo's `CODING_GUIDELINES.md`
(Header Files) is the full source of truth.

## 1. Include group order

Group includes, one blank line between groups, in this order:

1. The corresponding header (in a `.cpp`/`.mm`): `#include "foo.h"`.
2. Local project headers, relative to the target's include root:
   `#include "renderer/frame_context.h"`, `#include "../pipelines/vulkan_render_pipeline.h"`.
3. Public headers: `#include "vertexnova/rhi/device.h"`.
4. System headers: `#include <vector>`, `<string>`, `<memory>`.
5. Third-party headers: `#include <imgui.h>`.

`.clang-format` sets `SortIncludes: false` and `IncludeBlocks: Preserve`, so the
formatter will neither sort nor regroup includes. Order them by hand, alphabetically
within each group, and keep the blank-line separators.

## 2. Header self-containment

Every `.h` must compile on its own. Include what you use directly in the header;
never rely on a type being pulled in transitively by another include or by the
`.cpp` that includes it. If a header names `Device` or `SurfaceDescriptor`, that
header includes or forward-declares it, not its callers.

## 3. Forward declarations

Prefer a forward declaration over an include when only a pointer or reference is
used in the header. Include the full definition only when the layout is needed
(by value, base class, container element, or member access).

## 4. Header structure

- `#pragma once` first, then the copyright banner block.
- Then: includes (grouped as above), forward declarations, `namespace`, then the
  class / struct / enum. Close with `}  // namespace vne::...`.

## 5. Objective-C++ import order

In `.mm` files: `#include` C++ headers first, then `#import` Objective-C headers,
then system frameworks (guarded by platform macros where needed).

## 6. After editing includes

Run `python3 scripts/clang_formatter.py all` (or add `--dry-run` to check), then
build. Because sorting is off, a build is the only check that an include is
actually present: a header that compiles only because a sibling included it first
will break the moment include order changes. See
[vne-build-verify](../vne-build-verify/SKILL.md).