# Ascii Header Formatting

> Enforce ASCII-only section headers and comment banners. Use when writing or reviewing code comments, section dividers, or banner headers in any source file. Do not use Unicode box-drawing characters. Use when this capability is needed.

- Skill: `tomevault-io/ascii-header-formatting` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/ascii-header-formatting`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/ascii-header-formatting/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/ascii-header-formatting

---


# ASCII Header Formatting

All section headers and comment banners in source files must use only plain
ASCII characters. Unicode box-drawing characters (e.g. `─`, `━`, `│`, `╔`,
`═`) are forbidden.

## Rules

- Use `-` for horizontal rules and divider lines.
- Headers must be padded with trailing `-` characters so that the full line
  reaches column 80 (the standard ruler width).
- The format is `// -- <title> <filler>` where `<filler>` is as many `-`
  characters as needed to make the total line length exactly 80 characters.
- Indented headers (inside a module or `module private`) follow the same rule,
  counting the leading spaces as part of the line length.
- Apply consistently across F#, C#, and Scheme source files in this repo.

## Examples

**Correct** — line is exactly 80 characters wide

```fsharp
// -- Public API ---------------------------------------------------------------
// -- Helpers ------------------------------------------------------------------

    // -- Lambda ---------------------------------------------------------------
    // -- Variable lookup with capture tracking --------------------------------
```

To compute filler length: `80 - len("// -- <title> ")` dashes.

**Incorrect** — too short, or using Unicode box-drawing characters

```fsharp
// -- Public API --------------------
// ─── Public API ───────────────────
// ━━━ Helpers ━━━━━━━━━━━━━━━━━━━━━
```

## Normalization Standard

Throughout the Feersum codebase, **only the single-line `// -- Title ---...` format is acceptable**. Older code may still use three other patterns; these must be migrated:

### ❌ Three-line block with equals (used in test files)
```fsharp
// ============================================================================
// Tests: local variable counts
// ============================================================================
```
**Migrate to:** `// -- Tests: local variable counts --...` (to column 80)

### ❌ Centered equals headers (used in Lex.fs, Parse.fs)
```fsharp
// =============================== Utilities ==================================
```
**Migrate to:** `// -- Utilities --...` (to column 80)

### ❌ Dashes without `-- ` prefix (used in LibrariesOld.fs, Builtins.fs)
```fsharp
// -------------------- Public Libraries API ---------------------
// -------------- Title --------------------
```
**Migrate to:** `// -- Public Libraries API --...` (to column 80)

### Why standardize on `// -- Title ---`?
- **Single line** is more maintainable (easier to search, update, and refactor)
- **Dashes are more readable** than equals in code context
- **Column 80** is the standard ruler width across the project
- **`-- ` prefix** creates visual consistency for all section levels
- **Nested indentation** (4-space modules) preserves the 80-char rule naturally

---
> Source: [iwillspeak/feersum](https://github.com/iwillspeak/feersum) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-06-19 -->