mdpact

structure/no-sections

severity: warningcategory: structurefixable: no

Long specs should be broken into sections with H2+ headings.

structure/no-sections

Severity: warning Category: structure Fixable: no

What it catches

A spec longer than 200 lines (configurable) that has fewer than two H2 or deeper headings.

Why it matters

Long unbroken prose is the hardest thing in the world to lint, review, or update. Without sections, rule scope becomes implicit ("this paragraph on line 247" rather than "the Tools section"), diffs become noisy, and agents have to hold more context to answer any one question. Sections give you cheap addressability.

Options

Example — good

A 300-line spec with ## Commits, ## Style, ## Tools, ## Review.

Example — bad

A 300-line spec with one H1 and no sub-headings.

good.md
---
version: 1
owner: team
---

# Spec

## Overview

Short spec — no-sections rule only fires on long specs.

## Style

Use tabs.
bad.md
---
version: 1
owner: team
---

# Big unstructured spec

This spec intentionally has no H2 headings. It's short for test ergonomics, but the linter is configured via `fixtures/config.json` to fire at 10 lines so the test stays tight.

Always use tabs. Prefer single quotes. Never commit secrets. Always commit before pushing. Use `rg` instead of `grep`. Prefer TypeScript. Document exports. Keep PRs under 400 lines. Review security-sensitive diffs with two people. Deploy via the CD pipeline only. Never run migrations by hand.